Externí systémy pro zpracování hromadné korespondence

V průbehu let 2017 - 2019 bylo implementováno propojení na externí systém hromadné korespondence. Narozdíl od dosavadního řešení, kdy se z formulářů HK0010, HK0020 a HK0030 exportují data přímo do MS Office (Word, Excel) na stanicích klienta (a ztrácí se tak kontrola nad vytvořenými soubory), tento nový systém pracuje na serveru a udržuje tak soubory neustále pod kontrolou. Toto se bude v budoucnu hodit v okamžiku, kdy školy začnou používat elektronický podpis pro podepisování výsledných PDF dokumentů, ale i v jiných případech, například při zasílání (byť elektronicky nepodepsaných) dokumentů do spisových služeb.

V rámci CRP projektu byla oslovena firma Marbes Consulting, která na zákazku implementovala tento modul. IS/STAG je připraven případně podporovat i jiné takové moduly, aktuálně ale existuje pouze jedna implementace, která je popsána na této stránce.

Propojení IS/STAG a modulu externí hromadné korespondence od Marbes Consulting je nasazeno na následujících školách (stav k 1.3.2024): ZČU, JČU, OSU, UPOL, UPCE, UTB, AVU, TUL.

Stručný návod pro běžné uživatele je k dispozici na stránce Zákazníci / Hromadná korespondence.

Úvod

Hrubý návrh architektury řešení lze nalézt v prezentaci z Mikulova 2017 na stránce 12-13. Prezentace o dalším postupu byly i na semináři 2018 a 2019.

Obsah

1. Obecný popis tohoto propojení, možnosti
2. Způsob a podmínky nasazení
3. Konfigurace IS/STAG
4. Instalace externí aplikace
5. Konfigurace externí aplikace a klientských počítačů
6. Sledování chyb v propojení s externí aplikací

Obecný popis tohoto propojení, možnosti

Propojení IS/STAG a aplikací externí hromadné korespondence je realizováno v následujícím rozsahu:

• Přenos šablony a dat do externí aplikace
  
  • Ve formulářích HK0010/20/30 existuje nové tlačítko "Web generování". Kliknete-li na něj, dojde k vygenerování zdrojových dat a jejich zaslání externímu systému, který začne ze šablony vytvářet jednotlivé dokumenty (pracuje postupně sám, na pozadí).
  • Zároveň dojde k otevření webového prohlížeče v portálu IS/STAG na záložce "IS/STAG / Reporty / Hromadná korespondence", kde se nachází vstupní bod externí aplikace.
• Práce v externí aplikaci
  
  • Externí aplikace se zobrazí v novém okně či záložce prohlížeče
  • Umožňuje náhled vygenerovaných dokumentů a případně i práci s nimi - tyto dokumenty lze upravovat (lze je otevřít ve Wordu, upravit a uložit)
• Práce s výslednými PDF dokumenty
  • Výsledné dokumenty lze stáhnout - buď jednotlivě a nebo hromadně v ZIP archivu či si nechat všechny dokumenty vložit do jednoho PDF
  • Výsledné PDF dokumenty zůstávají k dispozici v externí aplikaci (dokud dávky neuzavřete nebo nesmažete)
  • Dávku lze označit za hotovou - tím dojde k jejímu uzavření. V případě, že chcete takto vygenerované dokumenty nechat poslat rovnou do spisové služby, dojde v tuto chvíli k jejich odeslání do IS/STAG, který je umí následně předat spisovce.

Způsob a podmínky nasazení

Prvotní vývoj proběhl v rámci CRP 2017 (a dalších následných) projektu, v němž bylo domluveno, že vlastní nasazení modulu u zákazníka bude zpoplatněno jednorázovou částkou adresovanou firmě Marbes. Podmínky jsou k dispozici na stránce pro zákazníky.

Od začátku roku 2022 se o instalaci / nasazení / správu / provoz / upgrady aplikace hromadné korespondence i aplikace elektronického podepisování stará výhradně firma Marbes Consulting, tj. z hlediska vývojového týmu IS/STAG se jedná o externí aplikaci, na jejímž nasazení a provozu se naši zákazníci dohodnou s firmou Marbes Consulting a IS/STAG je následně s aplikací pouze technicky propojen poté, co je její instalace připravena.

Konfigurace IS/STAG

Tato kapitola popisuje kroky nutné pro konfiguraci IS/STAG tak, aby byl napojen na systém webové hromadné korespondence.

Spammer - automatické zprávy - pro administrátory IS/STAG

Silně doporučujeme administrátorům, aby si v aplikaci na portálu IS/STAG "Automatické zprávy (spammer)" (sekce IS/STAG) zapnuli odběr zpráv "Přenos dat s jinými systémy - chybová hlášení". Budou jim pak každý den chodit seznamy chyb, které se staly při komunikaci s jinými systémy během uplynulého dne/víkendu. Případné detaily zaslaných informací si pak mohou dohledat v aplikaci na portálu, viz. kapitola o monitoringu propojení s externími systémy.

Parametry IS/STAG

• HK_WEB = "A" (na úrovni REK). Tento parametr nastavit až jako POSLEDNÍ věc konfigurace, tímto parametrem se propojení zapíná!
• HK_MARBES_URL = "https://stag-doc.SKOLA.cz/uni" (na úrovni REK) - Nastavte URL adresu, na které je aplikace od firmy Marbes nasazena. Typicky to bude adresa "https://stag-doc.SKOLA.cz/uni".

Konfigurace modulu webových služeb IS/STAG

SOubor prosím sami neupravujte, kontaktujte vývojový tým IS/STAG. V konfiguračním souboru webových služeb (~/PORTAL-data/konfigurace/ws-config.properties) je potřeba pouze:

# ----------------------------------------------------------------------------------------
#  HK - Marbes - Pristup k externi hromadne korespondenci
# ----------------------------------------------------------------------------------------

# Jmeno/heslo pro volani (HTTP overeni)
hk_marbes_username = stagd
hk_marbes_password = NEJAKESILNEHESLO

# jaka uzivatelska jmena posilat do Marbes aplikace. Default 'orion', jinak lze prenastavit na 'stag'
#hk_marbes_username_type = orion | stag
 
# postfix pridavany za uzivatelska jmena - muze se hodit na oddeleni vice uzivatelu ci treba napojeni ostre i DEMO nad ten samy system
#hk_marbes_usernames_postfix = @demo.zcu.cz 

• Parametr hk_marbes_username_type říká, jaká uživatelské jména má vytvářet IS/STAG v externí aplikaci pro uživatele IS/STAG. Mělo by mít stejnou hodnotu, jako má parametr "stag.user.identita" v konfiguračním souboru portálu stag-config.properties. Hodnota "orion" bude předávat ta "externí" uživatelská jména (typicky velké školy, výchozí hodnota), hodnota "stag" použije uživatelské jméno IS/STAG identity.
• Parametr hk_marbes_username, hk_marbes_password - uživatelské jméno a heslo, které použít pro vzájemné ověření při volání služeb mezi IS/STAG a externí aplikací. Uživatelské jméno doporučujeme nechat "stagd", heslo nějaké náhodné silné - stejné se pak zapíše i do konfigurace Marbes aplikace.
• Parametr hk_marbes_usernames_postfix - je-li uvedeno, přidá to k uživatelskému jménu v ext. aplikaci nějaký postfix. Může se hodit například když budete chtít provozovat jednu instanci Marbes aplikace pro Váš produkční i pro DEMO systém (aby nebylo nutné dělat pro DEMO další virtuál). Na ZČU budeme používat jeden server pro více outsourcovaných zákazníků.
• Dále pak změnit hodnotu parametru spring.profiles.active - přidat (čárkou odděleně, pokud ještě není) hodnoty "esb" a "hk_marbes", čímž se funkcionalita propojení zapíná. Výsledek by měl vypadat přibližně takto (může tam být více i dalších možností, ale alespoň tyto by měly být):

spring.profiles.active = stag_services, esb, hk_marbes

Instalace externí aplikace

POZOR NOVINKA OD ZAČÁTKU ROKU 2022 - O instalaci i konfiguraci aplikace STAGD a QSIGN se již zcela a plně starají školy ve spolupráci s dodavatelem - firmou Marbes Consulting - na základě servisní smlouvy. My zde ponecháváme STAROU dokumentaci jen pro úplnost, ale je již zcela bez záruky!

Domluva s firmou Marbes je taková, že:

1. Zákazník kontaktuje vývojáře IS/STAG přes RT a domluvíme se
2. Zákazník se následně dohodne s firmou Marbes na zaplacení instalačního poplatku a uzavření smlouvy o supportu - viz kapitola způsob a podmínky nasazení.
3. Zákazník zajistí vytvoření (virtuálního) serveru, stejným způsobem, jako zajišťuje server pro provoz například portálu IS/STAG. U zákazníků, kteří mají řešení outsourcované na ZČU, tento bod zajístí ZČU. Podrobnosti k zakládanému serveru:
   • DNS hostname: stag-doc.SKOLA.cz
   • 4 GB RAM
   • 80 GB diskového prostoru
   • 4-8 CPU
   • Funkční linux systém napojený na Vaši infrastrukturu
4. Následně my (vývojáři IS/STAG) zajistíme přípravu systému na tomto serveru tak, aby odpovídal naší platformě pro provoz aplikací a nainstalujeme tam i aplikaci od fy. Marbes. Konfiguraci máme provedenou nástrojem Puppet stejně tak, jako udržujeme konfigurace i ostatních strojů s našimi webovými aplikacemi.
5. Po vytvoření serveru upravit konfigurační soubor aplikace (připravený puppetem na cestě /opt/tomcat9/PORTAL-data/read-write/uni/WEB-INF/application.properties ) - nahradit cestu do databáze a hesla.

Konfigurace externí aplikace a klientských PC

Manuál pro konfiguraci externí aplikace je dodávám firmou Marbes. Zde je výňatek důležitých informací:

Databázové schéma pro externí aplikaci

Aplikace vyžaduje svoje databázové schéma v Oracle databázi.

Dříve: My typicky pro tuto aplikaci vytváříme schéma přímo v databázi IS/STAG, schéma pojmenované "STAG_MARBES_UNI". Doporučujeme to udělat stejně. Heslo k tomuto schématu (=DB uživateli) je nutno uvést do konfiguračního souboru aplikace.

Nově: Během dlouhé dobu provozu Marbes aplikace v "našem STAG databázovém prostoru" jsme si všimli, že Marbes aplikace dělá "šíleně moc opakovaných neoptimalizovaných SQL dotazů", které ze začátku při prázdné DB nevadí, ale kdž se pak postupně plní daty, začínají čím dál více vytěžovat databázi (a tedy v důsledku "překáží" i normálním operacím v IS/STAG, jejichž funkčnost Vám garantujeme...). Proto s platností od zjištění těchto poznatků (tj. řekněme od roku 2022-23) bychom Vám toto nedoporučovali a naopak bychom Vám doporučovali umístit tu databázi pro Marbes někam zcela odděleně (tj. i fyzicky, aby případné vytížení zdrojů jejich databáze neovlivnilo zdroje databáze STAGu).

Pouze domněnka/nápad, ale: Nevíme, teoreticky, zda dokonce Marbes nepodporuje jiné než Oracle databáze, možná se můžete zkusit poptat...

Podporovaný formát šablon

Aplikace podporuje pouze formát .docx. Tj. je případně potřeba staré .doc soubory převést do tohoto novějšího formátu.

Upozornění: Aplikace má problém, pokud použijete například příponu .docm (soubor s makry). Používejte prosím výhradně .docx.

Instalace fontů pro LibreOffice

V případě použití jiných, než standardních fontů, je potřeba tyto nainstalovat přímo na server, na němž probíhá generování dokumentů.

Základní fonty lze nainstalovat:

sudo apt install fonts-liberation

Pro správné fungování konverze je však nutné v systému nainstalovat fonty, které se využívají v konvertovaných dokumentech. Tyto fonty je nutné získat od zákazníka, pokud se nejedná o standardní fonty operačního systému. Po instalaci fontů je nutné restartovat procesy LibreOffice. LibreOffice neumí načítat nové fonty za běhu.

LibreOffice využívá fonty ze složky /usr/local/share/fonts/ (případně ze složky ~/.fonts). Fonty stačí do dané složky nakopírovat. Složka je globální pro celý systém. Složka ~/.fonts je v domovském adresáři přihlášeného uživatele (pozn. složka v adresáři uživatele je skrytá). V případě instalace fontů do uživatelské složky je nutné zajistit, aby se jednalo o stejného uživatele, pod který poběží aplikace. Ideálně ale postupovat podle dokumentace k Debian Linuxu ohledně fontů - tj. pak ještě spustit příkaz "fc-cache".

Poznámka: Automatizovaná instalace přes Puppet (kterou dělalo kdysi ZČU) přidává tyto fonty, přidává i fonty pro použití v čárových kódech (fonty odkazované z této stránky). Není tak třeba fonty řešit, pokud nechcete nějaké další. V případě instalace dodavatelem Marbes si to ale ohlídejte.

Sledování chyb v propojení s EXTERNím systémem hromadné korespondence

Přečtěte si prosím nejprve informace, které se tohoto tématu týkají obecně - na stránce o propojení s externími systémy. Případné chybové hlášky by měly být k dispozici prostřednictvím aplikace pro správu externích systémů jak je uvedeno za uvedeným odkazem. V každém případě - při problémech s propojením je třeba prostudovat i log soubory modulu webových sluzeb, protože ne všechny detaily a informace se přenášejí zpět do databáze IS/STAG.