Menu
▾
▴
Systemdokumentasjon
Byggemiljø og prosjektarkitektur
Maven er benyttet for applikasjonshåndtering. Prosjektarkitekturen er lagdelt, hvor mxa-war er det øverste laget. Det er WAR-filen fra dette laget som blir rullet ut. Under følger en liste med programmer som er benyttet under utvikling med tilhørende versjonsnumre og en kort beskrivelse.
| Program | Versjon | Beskrivelse |
|---|---|---|
| Maven | 3.0.4 | Prosjekthåndtering, styring av modulavhengigheter med mer. |
| Nexus | 2.x.x | Dependency proxy / internt maven repository. |
| Jenkins | 1.4xx | ContinuousIntegration. Automatisk bygging og kjøring av tester ved svn commits. |
| Svn | 1.6.x | Versjonskontroll av kildekode. |
| Spring Tool Suite | 2.9.x | Springsource sin versjon av Eclipse. |
| SQLDeveloper | 3.1.x | Visuelt Oracle databaseverktøy. |
| Tomcat | 7.x | Applikasjonsserver. |
| Java JDK | 1.7 | Java JDK |
Byggemiljø og kildekode
Kildekoden er tilgjengelig her på sourceforge.
I rot mappen ligger rot-pom’en. Det er i denne mappen man hovedsakelig kjører maven goals. Under følger en liste med ofte kjørte goals.
- mvn clean install
- mvn test
- mvn surefire-report:report
UTF-8 er benyttet i hele prosjektet, med unntak av error.jsp (ISO-8859-1).
Utviklingsmiljø
Eclipse er brukt til utvikling, men ingen IDE-spesifikke filer skal være sjekket inn i versjonskontroll, og man skal kunne bruke ett annet IDE hvis man ønsker det.
Prosjektarkitektur
Figuren under viser lagdeling av applikasjonen. Selve applikasjonen vises til høyre.
Integrasjonstestene og databaseskriptene ligger i separate mapper.
| mappe | beskrivelse |
|---|---|
| mxa-war | Web-service som mottar meldinger fra eksterne systemer. Administrasjonsmodulen (JSF GUI), ligger også i dette laget. |
| mxa-service | Quartz-jobber, tjenester til webservice-laget. Dette laget tar seg av all kommunikasjon med Altinn. Tre jobber kjører. 1. Ser etter nye meldinger for videresending til Altinn. 2. Henter kvitteringsfil fra FTP og oppdater meldingsstatus.3. Sender epost-varsel hvis en melding ikke er lest innen frist. Sender sak til Etaten for manuell behandling, hvis meldingen ikke er lest innen 14 dager over første lesefrist. |
| mxa-repository | Hibernate repositories, hibernate-mappings, data source, transaction manager |
| mxa-altinn | ws-Autogenerert kode med tynt overbygg (adapter). |
| mxa-domain | DTO-objektene og repositories |
Database og applikasjonsserver
Dette kapittelet beskriver databasen, innholdet i denne og applikasjonsserveren som kjører MXA.
Database
Keyvalues
Tabellen KEYVALUES inneholder grunndata som er parametere som kan endres ved behov. Alle verdiene i tabellen leses kun når applikasjonen startes opp, så applikasjonen må restartes før endringer i keyvalues tas i bruk.
| KeyValue | Eksempelverdi | Beskrivelse |
|---|---|---|
| SYSTEMUSERNAME | ETAT | SYSTEMUSERNAME er etatens bruker hos altinn. Kan også tenkes på som brukernavnet til correspondence webtjenesten. I versjon 2.40 og eldre het denne GOVORGAN. |
| SYSTEMUSERCODE | ETAT_1 | Kode for kildesystem. Tre første bokstaver representerer tjenesteeier. Etterfølgende tegn representerer avdeling/system. I versjon 2.40 og eldre het denne GOVORGAN. |
| LANGUAGECODE | 1044 | Språkkode i Altinn. 1044 er norsk bokmål |
| ALTINNPASSWORD | passord123 | Passordet tilhørende webtjenesten i Altinn |
| SMTPHOST | 10.0.0.25 | Utgående mailserver benyttet for å sende mail |
| SMTPUSER | Brukernavn på mailserveren. Settes til null hvis autentisering ikke benyttes | |
| SMTPPASSWORD | Passord på mailserveren. Settes til null hvis autentisering ikke benyttes | |
| MAILFROM | altinn-varsel@etaten.no | Avsender på mail som sendes fra MXA |
| RECEIPTFTPSERVER | 10.0.0.21 | FTP-server hvor kvitteringsfilene fra Altinn ligger |
| RECEIPTFTPPATH | /altinn/kvittering | Filsti på FTP-serveren hvor kvitteringsfilene ligger |
| RECEIPTFTPUSER | ftp_brukernavn | Bruker på FTP-serveren |
| RECEIPTFTPPASSWORD | ftp_passord123 | Passord på FTP-serveren |
| MAILNOTICESUBJECT | Brev fra Etaten er tilgjengelig i Altinn | E-post tittelfelt |
| MAILNOTICECONTENT | Du/dere har mottatt et brev (en melding) fra Etaten i Altinn portalen. Meldingen var tilgjengelig for ca en uke siden og vi kan ikke se at den er lest. Meldingen gjelder: ${messageHeader} Trenger du hjelp? For å logge inn på Altinn portalen kan du følge denne lenken www.altinn.no Her finner du veiledninger og Altinns brukerstøtte kan bistå. Dersom du ønsker å snakke med noen i Etaten, kontakt vårt infosenter på telefon: +47 00 00 00 00 (mandag - fredag 9.00 - 15.00) Dette er en automatisk generert mail. Etaten er i henhold til e-forvaltningsforskriften forpliktet til å sende slikt varsel. Med vennlig hilsen Etaten-E-post hovedtekst med ${messageHeader} | |
| MAILTOPAT | altinn-varsel@etaten.no | Mottaker adresse for meldinger som har gått over tiden. Se MAILWARNDAYS |
| MAILWARNSUBJECT | Brevet sendes pr post | ikke lest i Altinn-E-post tittelfelt |
| MAILWARNCONTENT | Meldingen gjelder: ${messageHeader} eller ${messageSummary} Med vennlig hilsen | |
| Administrator MXA E-post hovedtekst med ${messageHeader}, ${messageSummary} | ||
| NOTIFICATIONTYPE | ETA_NAVN_PAA_MAL | Navn på varslingsmalen i Altinn |
| SERVICECODE | 1234 | Autogenerert tall fra Tjenesteutviklerløsningen (TUL) for meldingstjensten |
| SERVICEEDITION | 1 | Versjon av medlingstjenesten |
| MAILNOTICEDAYS | 7 | Antall dager en melding kan være ulest før det sendes varsel fra MXA |
| MAILWARNDAYS | 14 | Antall dager en melding kan være ulest før saken sendes til MAILTOPAT for manuell behandling. |
Backup av databasen
Det bør tas backup av databasen daglig. IT-drift sørger for at backup kjøres i henhold til Etatens prosedyrer.
Bakgrunnsjobber (Quartz)
I MXA er det tre jobber som kjøres automatisk i batch:
- cronCheckNewMessages sender nylig ankomne meldinger videre til Altinn
- cronConfirmationBatch henter kvitteringsfiler fra Altinn og oppdaterer status på leste meldinger i databasen
- cronSendDeviationNoticeAndWarn sender varsling pr. e-post og saken som e-post hvis den ikke er lest innen fristen. Antall dager notis og varsel sendes er konfigurert i KEYVALUES tabellen.
Jobbene kjøres av et Java-rammeverk som heter Quartz. Det er ett sett med tabeller i databasen som brukes av Quartz-rammeverket, men bare to av dem er interessante i administrasjonssammenheng: QRTZ_CRON_TRIGGERS og QRTZ_TRIGGERS.
Alle Quartz-tabellene er har prefix QRTZ_ i tabellnavnet. I tabellen QRTZ_CRON_TRIGGERS ligger en CRON_EXPRESSION som bestemmer når de forskjellige jobbene skal kjøre. Se Quartz-doumentasjonen for beskrivelse av formatet på CRON_EXPRESSION: http://www.opensymphony.com/quartz/api/org/quartz/CronTrigger.html.
MXA må omstartes for at de nye verdiene skal tre i kraft.
Det er også mulig å tvinge en jobb til å kjøre umiddelbart ved å sette -1 i kolonnen NEXT_FIRE_TIME i tabellen QRTZ_TRIGGERS. Denne tabellen inneholder også en kolonne som viser når jobben kjørte sist.
Applikasjonsserver
Konfigurering av Tomcat
MXA kjører på Apache Tomcat webtjener. Tomcat må konfigureres før MXA rulles ut.
Roller og brukere
Rollen mxaadmin og brukere som har denne rollen må legges inn i filen $TOMCAT_HOME/conf/tomcat-users.xml. Her er et eksempel på tomcat-users.xml:
<tomcat-users></tomcat-users>
<rolerolename="mxaadmin"></rolerolename="mxaadmin">
<user username="admin" password="admin123" roles="mxaadmin"></user>
Port
Tomcat kjører som standard på port 8080. Dette kan endres til standard web-port, som er 80, ved å endre følgende i $TOMCAT_HOME/conf/server.xml:
<Connector port="80" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8443" />
Utrulling av applikasjon
Gjør følgende for å rulle ut en ny versjon av MXA:
- Stopp Tomcat
- Slett mappen $TOMCAT_HOME/webapps/mxa, filen $TOMCAT_HOME/webapps/mxa.war og mappen $TOMCAT_HOME/ work hvis de eksiserer.
- Kopier ny versjon av mxa.war til folderen $TOMCAT_HOME/webapps (de slettede mappene, mxa og work, vil bli opprettet på nytt når Tomcat starter)
- Start Tomcat
Tomcat ruller nå ut MXA automatisk, og starter MXA.
Logging
Tomcat skriver logger i folderen $TOMCAT_HOME/logs. Den mest interessante loggen er stdout_YYYYMMDD.log. De andre loggene kan i noen tilfeller være interessante spesielt hvis applikasjonen ikke starter som den skal. Normalt skal det ikke være behov for å følge med på disse loggene. Applikasjonen logger også til databasen som normalt er mer interessant for en administrator å følge med på.
Konfigurasjonsfilen for logging: $TOMCAT_HOME/webapps/mxa/WEB-INF/classes/log4j.properties
For å sette log-level til trace:
log4j.logger.no.mxa.altinn.ws.api=TRACE
log4j.logger.no.mxa.service.altut=TRACE
log4j.logger.no.mxa.ws=TRACE
log4j.logger.no.mxa.ws.model=TRACE
log4j.logger.no.mxa.ws.webservice=TRACE
log4j.logger.no.mxa.ws.parser=TRACE
Epost-varsling
MXA sender e-post til kunder hvis de ikke har lest meldingene innen X antall dager og til konfigurert e-postkasse hvis meldinger ikke er lest innen Y antall dager. Dette er konfigurert i KEYVALUES tabellen. MXA bruker en SMTP-server definert i KeyValues for å sende mail. SMTP-serveren må godta at MXA sender mail uten autentisering. Autentisering kan konfigureres ved å sette brukernavn og passord i keyvalues, men javamail støtter bare LOGIN, PLAIN og DIGEST-MD5 som autentiseringsmekanismer men ikke NTLM som er standard for Microsoft Exchange.
FTP-oppsett
Altinn sender kvitteringsfiler for hvilke meldinger som er lest i en XML-fil som kommer hver natt. Altinn legger disse filene på etatens FTP-server (konfigurert i keyvalues) Filene har navnekonvensjon i henhold til bestillingen sendt Altinn.
MXA leser alle .log-filer og .xml i disse folderene og flytter dem til underkatalogen ./processed/ etter prosessering. MXA bruker FTP for å koble seg opp mot denne serveren, og det er derfor viktig at det ikke er noen brannmur eller lignende som sperrer for dette mellom disse maskinene.
Meldingsflyt og tilstandsdiagram
Meldinger som sendes til MXA kan ha mange ulike statuser underveis i flyten. Dette kapittelet oppsummerer hovedløpene for meldingsflyt inn og ut av MXA, samt hvilke verdier i databasen som bestemmer status på en gitt melding. I tillegg er det beskrevet hvilke manuelle oppfølgingshandlinger som kan utføres av en administrator gjennom det web-baserte administrator grensesnittet, og hvilke verdier i databasen som endres når handlingene utføres. Automatiske oppfølgingshandlinger er også dokumentert.
Meldingsflyt inn og ut av MXA
Meldingsflyten kan deles inn i tre separate deler:
Melding mottas i MXA via web-service
Når web-servicen i MXA har kvittert for at lagring av en melding har gått bra settes MSG_STATUS til 10, mens SENTALTINN settes til 0. Det er kombinasjonen av disse verdiene som gjør at en melding plukkes opp av den automatiske jobben som sender meldingen videre til Altinn. Lesefristen READDEADLINE settes til dagens dato pluss KEYVALUES.MAILNOTICEDAYS.
Dersom web-tjensten ikke klarer å motta meldingen blir ikke denne lagret. Det er to feil som kan returneres, returkode 1 betyr at MXA ikke får lagret meldingen i databasen, mens returkode 2 betyr at XML-meldingen ikke validerte i henhold til skjemadefinisjonen. I begge tilfeller vil det bli logget et innslag i tabellen LOG. Innslag uten tilknyttede meldinger blir vist på en egen side i administrator grensesnittet.
Melding sendes til Altinn via web-service
MSG_STATUS = 10 og SENTALTINN = 0 gjør at meldingen plukkes opp for sending til Altinn. Dersom sendingen er vellykket settes MSG_STATUS til 20 og SENTALTINN til 1. Dersom sendingen feiler settes MSG_STATUS til 30 og SENTALTINN til 0. Ved feil vil ikke meldingen bli forsøkt sendt på nytt automatisk.
**
*NB:* I bestillingsskjema Bestilling - Tilgang til online innsending er det angitt utgående IP-adresse for meldingsleveranser til Altinn. Det er viktig at denne IP-adressen matcher med den faktiske IP-adressen til maskinen meldingene sendes fra. Hvis disse ikke er like returneres følgende feilmelding i meldingsleveransen til Altinn: Access denied**.
Kvitteringsmelding mottas fra Altinn via FTP
Ved mottak av kvitterings-fil via FTP oppdateres statusen for en gitt meldingsreferanse. Dersom meldingen har blitt lest i Altinn settes MSG_STATUS til 40. Dersom meldingen har blitt bekreftet i Altinn settes MSG_STATUS til 50. Siden kvitteringer for bekreftelse ikke støttes i Altinn i forbindelse med fagsystemintegrasjon er ikke denne statusen i bruk i MXA. Applikasjonen støtter dette, men siden feltet requireConfirmation alltid settes til 0 ved oversendelse vil kvitteringer for bekreftede meldinger aldri bli sendt fra Altinn.
Dersom en meldingskvittering ikke kan knyttes til en meldingsreferanse i databasen blir det logget en feil i tabellen LOG.
Tilstander og statuser for meldinger
Tabellen nedenfor viser hvilke verdier i databasen som bestemmer tilstand og status for en gitt melding. Alle verdiene ligger i tabellen MESSAGE.
| Felt | Verdi | Beskrivelse |
|---|---|---|
| SENTALTINN | 0 | Melding ikke sendt til Altinn |
| SENTALTINN | 1 | Melding sendt til Altinn uten feil |
| MSG_STATUS | 10 | Melding mottatt i MXA |
| MSG_STATUS | 20 | Melding sendt til Altinn |
| MSG_STATUS | 30 | Sending til Altinn feilet |
| MSG_STATUS | 40 | Melding lest i Altinn |
| MSG_STATUS | 50 | Melding bekreftet i Altinn NB: Støttes ikke i gjeldende versjon av Altinn i forbindelse med fagsystemintegrasjon, statuskoden er dermed ikke i bruk |
| MSG_STATUS | 60 | Sak sendt automatisk via epost |
| MSG_STATUS | 70 | Avvik manuelt fjernet |
| READDEADLINE | MAILNOTICEDAYS dager fra mottak i MXA | Lesefristen til en melding |
| OVERDUENOTICESENT | 0 | Epost-varsel ikke sendt |
| OVERDUENOTICESENT | 1 | Epost-varsel sendt |
Kombinasjonen av disse verdiene gir følgende tilstandsdiagram:
Tabellen under beskriver de ulike tilstandene. Tilstand 1 er en lovlig neste-tilstand fra alle andre tilstander, siden meldinger manuelt kan sendes på nytt til Altinn fra administrator grensesnittet. Dette er for oversiktens skyld utelatt i figuren.
| Tilstand | Beskrivelse | Lovlig neste-tilstand |
|---|---|---|
| 1 | Melding er mottatt i MXA | 2, 3 |
| 2 | Sending til Altinn feilet | 1, 4 |
| 3 | Melding er sendt til Altinn | 1, 5, 6 |
| 4 | Avvik er fjernet manuelt | 1 |
| 5 | Melding er lest i Altinn | 1 |
| 6 | Varsel om utgått lesefrist sendt | 1, 5, 7 |
| 7 | Saken er sendt til etaten som epost | 1 |
Oppfølgingshandlinger
For å sikre at mottakere av meldinger leser disse innen gjeldende tidsfrister er det implementert en del oppfølgingshandlinger i MXA. Disse er styrt av verdiene som hver melding har i databasen. Oppfølgingshandlingene er både automatiske og manuelle.
Send epost-varsel automatisk
Hvis en melding ikke har blitt lest i Altinn innen lesefristen sender MXA en varselmail til epost-adressen som er registrert i meldingen. Følgende verdier i databasen trigger denne hendelsen:
MSG_STATUS = 20 og SENTALTINN = 1 og READDEADLINE< dagens dato og OVERDUENOTICESENT = 0.
Dersom meldingen ikke har en epost-adresse som er tilknyttet en kunde blir eposten sendt til etatens administratoradresse. Etter at varsel er sendt oppdateres følgende verdier i databasen:
READDEADLINE settes (MAILWARNDAYS - MAILNOTICEDAYS) dager fram i tid fra tidspunktet hvor varsel ble sendt.
OVERDUENOTICESENT settes til 1.
Et nytt logginnslag blir generert, som forteller at automatisk varsel har blitt sendt.
Send sak som epost automatisk
Hvis en melding ikke har blitt lest i Altinn innen lesefristen som ble satt da varselmailen ble sendt sender MXA hele meldingen med alle vedlegg til etatens administratoradresse. Følgende verdier i databasen trigger denne hendelsen:
MSG_STATUS = 20 og SENTALTINN = 1 og READDEADLINE< dagens dato og OVERDUENOTICESENT = 1
Etter at saken er sendt til etaten for manuell oppfølging oppdateres følgende verdi i databasen:
MSG_STATUS = 60
Et nytt logginnslag blir generert, som forteller at meldingen automatisk har blitt sendt til etatens administratoradresse.
Send melding til Altinn manuelt
Administratorbrukere kan sende en melding til Altinn manuelt, selv om meldingen har blitt sendt tidligere, eller om meldingen har feilet tidligere. Når knappen trykkes oppdateres følgende verdier i databasen:
MSG_STATUS = 10
SENTALTINN = 0
I tillegg genereres et nytt logginnslag som forteller at meldingen er merket for re-sending til Altinn. Meldinger som akkurat har blitt mottatt i MXA kan ikke sendes manuelt før etter at den automatiske sendingen har blitt utført.
Send melding som epost manuelt
Administratorbrukere kan manuelt sende en melding med vedlegg til etatens administratoradresse. Når knappen trykkes blir eposten sendt, men ingen verdier oppdateres i databasen. Handlingen genererer et nytt logginnslag som forteller at meldingen har blitt sendt til Etaten manuelt.
Fjern avvik manuelt
Meldinger som har feilet i oversendelsen til Altinn vil bli vist som avvik. Hvis en melding ikke kan sendes på nytt manuelt kan det være ønskelig å fjerne denne fra avvikslista. For å gjøre dette må MSG_STATUS oppdateres ved hjelp av en SQL-kommando mot databasen med meldingsreferansen som parameter. Meldingsreferansen for en gitt melding er tilgjengelig i administrator grensesnittet. SQL-kommandoen for å oppdatere statusen for en melding med meldingsreferanse ’1234’ er som følger:
UPDATE MESSAGE SET MSG_STATUS = 70 WHERE MESSAGEREFERENCE = ’1234’;
COMMIT;
