Instalace

Vývojové oddělení připraví k instalaci aplikace následující:

• SQL skripty, soubory s příponou *.sql
• webovou aplikaci, za default označme exchanger.war
• statické zdroje, aplikace pojmenovaná aducid-resources.war

Dle typu SQL databáze je nutné spustit dodané skripty, aby se vytvořila struktura databázových objektů vyžadovaných aplikací exchanger.war.

V následujícím textu se budu odkazovat na domovský adresář aplikačního serveru Tomcat pod proměnnou $CATALINA_HOME. Kroky k instalaci modulů jsou následující:

• nahrát modul exchanger.war do adresáře $CATALINA_HOME/webapps
• nahrát modul aducid-resources.war do adresáře $CATALINA_HOME/webapps
• spustit aplikační server

Po úspěšném spuštění aplikačního serveru budou jednotlivé WAR moduly rozbaleny v adresáři $CATALINA_HOME/webapps v adresářích odpovídajících jménům WAR modulů.

V dodávce z vývoje je defaultně v modulu exchanger.war nastavena podpora databáze HyperSQL. Jedná se o lehkou databázi, která není vhodná pro produkční nasazení. Proto je nutné v modulu exchanger.war provést dodatečné úpravy. Nyní jsou podporovány dvě plnohodnotné databáze - MS SQL a PostreSQL. Podporu produkční databáze lze získat těmito úpravami:

• rozbalit modul exchanger.war
• zkopírovat obsah souboru src/main/webapp/WEB-INF/dispatcher-servlet-mssql.xml, resp. dispatcher-servlet-postgres.xml, a nahradit obsah souboru dispatcher-servlet.xml
• zabalit modul exchanger.war

Dále se s modulem exchanger.war pracuje dle popisu v kapitole Instalace WAR modulů. Popis konfigurace přístupu k databázím je popsán v kapitole Konfigurace/Infrastrukturní.

Konfigurace aplikace je uložena v souboru web.xml, který lze nalézt v cestě $CATALINA_HOME/webapps/exchanger/WEB-INF. Při úpravách konfigurace v tomto souboru doporučuji soubor zazálohovat. V případě aktualizace aplikace bude tento soubor nahrazen souborem z aktualizovaného modulu, a dojde tak ke ztrátě konfigurace. Po aktualizaci je tedy nutné zazálohovaný soubor nahrát zpět do adresáře $CATALINA_HOME/webapps/exchanger/WEB-INF, aby byla konfigurace aktuální pro dané prostředí. Po změně konfigurace je nutné restartovat aplikační server.

Konfigurace je realizována standardní cestou konfigurace webové aplikace, tedy množinou jmen a hodnot uložených v elementech context-param. Parametry lze rozdělit na skupinu závislých na infrastruktuře a skupinu ovlivňujících chování samotné aplikace.

Nastavení ADUCID:

• aimUrl - URL k AIM serveru, např. https://aim.demo.anect.com

Nastavení přístupu k SQL databázi:

• jdbc.url - JDBC URL pro připojení k SQL databázi, očekává se celý JDBC řetězec, tedy například:
  • PostgreSQL - jdbc:postgresql://host/exchanger
  • MS SQL - jdbc:sqlserver://host;databaseName=exchanger;
• jdbc.username - uživatelské jméno pro přístup k SQL databázi
• jdbc.password - uživatelské heslo pro přístup k SQL databázi

Nastavení přístupu k SMTP serveru:

• smtp.host - adresa serveru SMTP
• smtp.port - port serveru SMTP
• smtp.username - uživatelské jméno pro přístup k SMTP serveru
• smtp.password - uživatelské heslo pro přístup k SMTP serveru

Další nutné infrastrukturní parametry:

• global.repositoryPath - cesta k adresáři, kde se budou ukládat odesílané soubory, např. /opt/anect/exchanger/repo
• global.domainFile - cesta k souboru s definicemi domén, např. /opt/anect/exchanger/domain.txt, význam souboru je následující:
  • seznam definuje domény uživatelů, kteří mají povolenou samoregistraci (A level uživatelé)
  • na každé řádce může být pouze jedna maska domény
  • na konci souboru nesmí být prázdná řádka
  • pro povolení všech domén stačí do souboru uložit masku .*
  • masky se řídí definicí regulárních výrazů jazyka Java, více viz https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html

Globální parametry jsou následující:

• global.mailFrom - adresa, ze které jsou odesílány všechny emaily aplikace
• global.minExpirationInDays - minimální počet dnů vypršení platnosti zásilky, který je možný v GUI nastavit
• global.maxExpirationInDays - maximální počet dnů vypršení platnosti zásilky, který je možný v GUI nastavit
• global.defaultExpirationInDays - defaultní počet dnů vypršení platnosti zásilky, pokud uživatel hodnotu v GUI nedefinuje
• global.maxRecipientsCount - maximální počet příjemců, který je možný v GUI při odesílání přidat
• global.maxResendAttempts - maximální počet pokusů o opakování odeslání emailu
• global.maxUploadSizeInBytes - maximální velikost souboru, který lze nahrát do systému, musí se jednat o hodnotu dělitelnou číslem 1024*1024 (1048576 bytů = 1 MB), např. hodnota 1048576000 odpovídá hodnotě 1000 MB
• global.maxInMemorySizeInBytes - maximální velikost využité paměti serveru při uploadu souboru na server, musí se jednat o hodnotu dělitelnou číslem 1024*1024 (1048576 bytů = 1 MB), např. hodnota 104857600 odpovídá hodnotě 100 MB
• global.anonymousFileSuffix - automatická přípona anonymizovaných souborů uložených na disku
• global.requestExpirationInDays - maximální platnost nevyužitých/neodeslaných požadavků
• crypto.digestAlgorithm - algoritmus pro výpočet hash odesílaných souborů, podporované hodnoty jsou MD5, SHA-1 a SHA-256

Dále jsou uvedeny konfigurační položky automatických úloh, které jsou spouštěny na základě Cron definice. Jedná se rozšířenou Cron definici s podporou vteřin, více viz https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/support/CronSequenceGenerator.html. Konfigurační parametry jsou následující:

• scheduler.resendEmailCron - Cron definice automatické úlohy pro opakování odeslání nedoručených emailů, více viz Opakované odesílání emailů
• scheduler.checkLetterExpirationCron - Cron definice automatické úlohy pro označení zásilek jako expirovaných, více viz Kontrola vypršení platnosti zásilky
• scheduler.notifyRecipientCron - Cron definice automatické úlohy pro posílání notifikace uživatelům, které si ještě nestáhli zásilku, více viz Notifikace příjemce
• scheduler.checkRequestExpirationCron - Cron definice automatické úlohy pro odstranění nevyužitých/neodeslaných požadavků, jako jsou např. žádost o registraci, žádost o registraci dalšího emailu, atd., více viz Kontrola vypršení obecného požadavku

Aplikační kód zapisuje své chování do logu. Tento log je určený především pro počáteční ladění a nedoporučuji jej mít zapnutý v produkčním prostředí. Při dodání instalačních komponent pro instalaci do produkčního prostředí by měla být komponenta exchanger.war dodána již s vypnutým logováním.

Po úpravách konfigurace logování je nutné restartovat aplikační server.

Konfigurace obecného logování aplikace je uložena v souboru $CATALINA_HOME/webapps/exchanger/WEB-INF/classes/log4j.properties. Obsah v produkční podobě může vypadat následovně:

log4j.rootLogger=WARN, CONSOLE
log4j.logger.com.aducid.database=WARN
log4j.logger.com.aducid.exchanger=WARN
log4j.logger.com.aducid.web.controller=WARN

log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d [%-5p] Thread[%-21t] %m%n

V situaci zapnutého podrobného je obsah následující:

log4j.rootLogger=WARN, CONSOLE
log4j.logger.com.aducid.database=DEBUG
log4j.logger.com.aducid.exchanger=DEBUG
log4j.logger.com.aducid.web.controller=DEBUG

log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=%d [%-5p] Thread[%-21t] %m%n

Hodnoty s prefixem log4j.logger.com.aducid byly tedy změněny z hodnoty WARN na DEBUG. Při tomto nastavení se veškeré zprávy zapisují do souboru $CATALINA_HOME/logs/catalina.out.

Kromě obecného logování je možné navíc zapnout SMTP logování pro detailnější informace o komunikaci se SMTP serverem. Toto nastavení je uloženo v konfiguraci $CATALINA_HOME/webapps/exchanger/dispatcher-servlet.xml. Zde je zobrazena část konfigurace, kde lze měnit úroveň logování:

...
        <property name="javaMailProperties">
            <props>
                <prop key="mail.transport.protocol">smtp</prop>
                <prop key="mail.smtp.auth">true</prop>
                <prop key="mail.smtp.starttls.enable">true</prop>
                <prop key="mail.debug">false</prop>
            </props>
        </property>
...

Změnou hodnoty mail.debug na true lze docílit požadované změny. Informace se zapisují do logu nastaveném v obecné konfiguraci, defaultně tedy do souboru $CATALINA_HOME/logs/catalina.out.

V některých diagramech se pracuje s počtem pokusů o opakované odeslání, tj. textem ve smyslu 5 resend attemps. Pracuje se tedy s konkrétní hodnotou pěti pokusů o odeslání. Důvodem je jednodušší pochopení celé problematiky. Hodnotu počtu pokusů o odeslání je možné nastavit na libovolnou hodnotu úpravou konfiguračního parametru maxResendAttempts.

Součástí aplikace jsou automatizované úlohy, které provádí rozmanité úkoly. Podrobnější popis těchto úloh je zahrnut v kapitolách níže.

Tato úloha se stará o opakované odesílání emailů, pokud z nějakého technického důvodu nebyly odeslány. Každý neodeslaný email je označený jako *_NOT_SENT (prefix se liší dle typu emailu) a tato úloha se v pravidelných intervalech určených konfigurační hodnotou scheduler.resendEmailCron pokouší email znovu odeslat. Počet pokusů o doručení je určený konfigurační hodnotou global.maxResendAttempts. Při hodnotě Cron výrazu 0 0 * * * * a počtu pokusů o doručení nastavených na pět se úloha pokusí pětkrát odeslat email, a to každou celou hodinu. Pokud se ani poté email nepodaří doručit, je označen za nedoručitelný, tj. *_NOT_DELIVERABLE (prefix se liší dle typu emailu). Tato úloha se snaží odeslat následující neúspěšné emaily:

• žádost o registraci uživatele
• žádost o přidání dalšího emailu
• samotný email o zásilce
• notifikaci o zásilce
• žádost o reproofing

Úloha v pravidelných intervalech kontroluje datum vypršení platnosti zásilky. Pokud platnost zásilky vyprší, je zásilka označená za EXPIRED. V případě, že zásilka nebyla dosud stažena, je označena za EXPIRED_NOT_DOWNLOADED. Stavem EXPIRED jsou také označena metadata souboru a samotný soubor je fyzicky smazán v úložišti.

V okamžiku odeslání zásilky je vypočten datum, kdy má být příjemce zásilky notifikován, pokud si zásilku ještě nevyzvedl. Tento čas se nyní fixně rovná polovině doby platnosti zásilky. Pokud tedy odesílatel nastavil platnost zásilky na osm dní, je datum notifikace nastaveno na čtyři dny, a po těchto čtyřech dnech se v případě nestažení souboru příjemcem odešle příjemci notifikace. Pokud existuje problém s odesláním notifikace, vstupuje do hry úloha popsaná v kapitole Opakované odesílání emailů.

Tato úloha řeší situace, kdy byl emailový požadavek úspěšně odeslán, ale nebyl v požadované zpracován. Email tedy dorazil uživateli, ale uživatel v dané době neklikl na odkaz ve zprávě, aby tak dokončil příslušný proces. Standardní nastavení platnosti požadavku je deset dní. Úloha má za cíl takto nezpracované požadavky mazat, aby tak nedocházelo například k trvalé blokaci emailové adresy. Jedná se konkrétně o tyto situace:

• do systému byl nahrán soubor, který již poté nebyl odeslán (skončil ve stavu UPLOADED a již ne ve stavu SENT)
• nebyl zpracován požadavek na registraci uživatele (neskončil ve stavu APPROVED)
• nebyl zpracován požadavek na přidání emailu uživatele (neskončil ve stavu APPROVED)
• nebyl zpracován požadavek na reproofing uživatele (požadavek stále existuje)