Spisová služba GORDIC

Týká se škol: JČU, UPCE, UJEP, VFU

Po ukončení provozu produktu BBM spisová služba dochází k "hromadné migraci" škol (JČU, UPCE, UJEP, VFU) ke spisové službě Gordic. K implementaci napojení na IS/STAG dochází v první polovině roku 2024, k migraci dojde v brzké době také.

Přestože spisová služba podporuje standradní rozhraní dle národního standardu NSESSS, bylo z implementačních důvodů a na základě doporučení vývojářů spisové služby zvoleno proprietární, ale výhodnější XRG API.

Obecný popis tohoto propojení, možnosti

Propojení IS/STAG a této spisové služby je realizováno v následujícím rozsahu (popis jednotlivých událostí a obecných možností propojení je na úvodní stránce spisových služeb):

Propagace události z IS/STAG do spisové služby:
- Zakládání spisů studia a přijímacího řízení
- Vznik nové písemnosti
- Smazání/storno písemnosti
- Přiložení binárního souboru jako přílohy k písemnosti
- Převod uchazeče na studenta -> nový spis, přesun písemností z přijímacího řízení
- Ukončení studia studenta -> (vyřízení a ) uzavření spisu na straně SPS
- Přejmenování spisu (např. změna přjmení studentek...)
- Nahlížení do spisu studenta / uchazeče

Model spisů přijímacího řízení je totožný s původní spisovkou BBM - jedná se o velký spis per fakulta a rok. Liší se ovšem způsob, jak jsou jednotlivé písemnosti v tom velkém spisu rozděleny jednotlivým uchazečům, tedy to, jak jsou písemnsoti označeny, že patří k danému uchazeči:

Ve spisovce BBM bylo nastaveno, že IS/STAG má pro všechny písemnosti daného uchazeče udržovat jedno shodné číslo jednací - podle něj se pak písemnosti ve spisovce k danému uchazeči přiřazovaly. Po importu z BBM do Gordic budou tato "původní" čísla jednací uložena k písemnostem ve formě vlastnosti "CJIFIS" (číslo jednací z IFIS) a IS/STAG s tím z hlediska kompatibility počítá.
Jenže u nové spisovky nelze tento mechanismus použít - číslo jednací takto použít nelze. Proto používáme mechanismus použitý i u jiných spisovek - ke každé písemnosti týkající se konkrétního uchazeče přidáváme vlastnost "UCHAZEC" (Identifikátor uchazeče) a jako hodnotu vkládáme oborové číslo uchazeče (= uchazec_idno).
S autory spisovky a lidmi z BBM je domluveno, že identifikátory (PID) existujících spisů ze spisovky BBM budou převedeny na "externí" identifikátory v nové spisovce - tyto externí identifikátory STAG používá, takže by zapamatované identifikátory spisů na straně IS/STAG měly transparentně přežít migraci a ukazovat nově na spisy v nové spisovce.
První rok po migraci se bude stávat, že ve spisu přijímaček se nachází část písemností ještě vygenerovaných ve spisovce BBM (ty mají vlastnost "CJIFIS") plus pak i písemnosti vygenerované nově (ty mají vlastnost "UCHAZE"). Budete-li vkládat například příchozí písemnosti ručně, nastavujte jim v nové spisovce už tu vlastnost UCHAZE. IS/STAG při nahlížení do spisu provádí dvě volání podle obou vlastností a výsledek spojuje.

Přechod z bbm na gordic

Speciální kapitola platná pro VFU, JČU, UPCE a UJEP - veškeré naše poznámky/návody týkající se přechodu ze spisovky BBM na Gordic. Zde popisujeme samozřejmě pouze věci, které se týkají IS/STAG.

Navrhovaný postup migrace v hrubých bodech:

Zprovoznit si testovací instalaci spisovky Gordic na škole plus nakonfigurovat si tuto spisovku pro potřeby IS/STAG (dodavatel spisovky by měl vědět, co je potřeba nastavit, nastavoval nám to pro VFU...)
Vypnout pravidelné aktualizace testovací STAG databáze ( a nebo si dobře ukládat/zapisovat změny, které v něm provedete, abyste je mohli po obnovení DB zase aplikovat )
Projít si kapitoly zde uvedené níže a získat potřebné informace/hodnoty od správců/autorů spisové služby
Jakmile získáte alespoň základní informace (URL, uživatelské jméno na připojení a heslo), my vám pomůžeme nakonfigurovat náš modul WS
Následně pak můžete využít funkci, která přes API spisovky stáhne několik důležitých číselníků spisovky, které budete při konfiguraci potřebovat - přes portál / adminsitrace / externí systémy / akce / stažení číselníků spisovky.
- Získáte ZIP s několika XML soubory - tak, jak je spisovka vrací. Jsou tam typicky ID/kódy a pak nějaké popisy/hodnoty. Do konfiguračních parametrů a atributů na straně IS/STAG budete potřebovat ta ID/kódy.
Překonfigurovat si váš testovací/demo IS/STAG - podle kapitol uvedených níže - tedy změnit pečlivě parametry, číselníky, atributy, typt dokumentů, způsoby odeslání, mapování uživatelů ...
- Dobře si uložte/zapište, jaké všechny změny jste provedli, budete je pak potřebovat při produkčním přechodu
Zároveň nezapomeňte nad testovací spisovkou vyzkoušet i import/migraci dat z původní spisovky BBM - to se IS/STAG netýká - domluvte si to a nechte si naimportovat stav z BBM a následně otestujte, že funguje vkládání do spisu studentů/uchazečů
- POZOR - IS/STAG si pamatuje identifikátory spisů, které v minulosti vygeneroval. A předpokládá a stojí na tom, že ty spisy ve spisovce existují. Takže migrace je potřeba, STAG sám o sobě bude zakládat pouze zcela nové spisy (třeba zcela nově vzniklých studií či dalšího ročníku přijímaček). Proto je třeba nejdříve migraci provést. Chcete-li zkusit testovat ještě bez migrace, ozvěte se (a v testovacím STAGU ta ID spisů necháme "zapomenout").
A lze začít testovat - lze se například držet postupu uvedeného na této stránce.
- Nezapomeňte vyzkoušet/nasimulovat situace, kde jsme během jednání tušili největší potenciální komplikace - například souhru více studijních referentek nad jedním spisem studenta, vkládání do spisu studenta někým, kdo je zcela mimo jeho fakultu... a podobné situace.
- Vyzkoušejte také vložení písemnosti do spisu, který byl přemigrován z BBM a už něco obsahoval - a pak zkuste přes STAG nahlížení do spisu - zda budou vidět všechny dokumenty (staré z BBM i nové)
V "den D" se bude celý postup opakovat pro produkční systémy.

Jmenný rejstřík - informace

Chceme-li ve spisovce Gordic založit "vypravení/odeslání" (chceme-li říct "komu se má písemnost odeslat"), musime tuto osobu najít či zavést do číselníku osob spisovky.

- Nejprve voláme API metodu spisové služby "NajdiEsu" a hledáme osobu dle: Jmeno+Prijmeni+Datum narozeni (to je kombinace, kterou jsme vyhodnotili jako nejrozumnejsi z moznosti - co API spisovky umi a jaka data my mame). Je to vlastne velmi podobne tomu, jak hledame lidi ve statnim ROBu.

- nasledne volame "vytvorEsu" - ono se pouziva (dle specifikace spisovky) na zalozeni i na pripadnou úpravu. Takze my bud zalozime nebo data "obcerstvime tim, co mame ve STAGu". Predavame spisovce: - prijmeni, jmeno, datum narozeni, tituly, email, id datovky, postovni adresu (veskere jeji polozky)

Konfigurace IS/STAG

Tato kapitola popisuje kroky nutné pro konfiguraci IS/STAG tak, aby byl napojen na spisovovou službu Gordic.

Parametry IS/STAG

Následující parametry NEJSOU VOLITELNÉ, tj. není-li u parametru vysloveně uvedeno, že si můžete vybrat, musíte je nastavit přesně tak, jak je zde uvedeno! Zároveň platí, že v IS/STAG najdete i další parametry SPIS_xxx a podobné a pokud nejsou vysloveně zde zmíněné, tak je nechte prázdné (případně při přechodu z BBM ty parametry smažte)!

STAG_WS_URL = Parametr musí obsahovat URL na modul webových služeb, který běží nad příslušnou databází (kde je parametr nastaven) - POZOR, ať nemáte např. na demo databázi nastavenu adresu modulu webových služeb běžícího nad databází ostrou! Příklad hodnoty: "http://stag-ws.zcu.cz/ws"
OS_CISLO_ZAKAZAT_ZNOVUPOUZITI = "A" - Tento parametr musí být při použití této spisové služby nastaven. Jinak by mohlo dojít k situaci, kdy se písemnosti budou vkládat do spisu, který byl již jednou použit.
SPIS_BINARNI_PRILOHY = "A"
SPIS_EPR_ELEKTRONICKY_OBRAZ = A/N - nastavte si tak, jak potřebujete (podporované obě možnosti)
SPIS_KDO_PRIRADI_CISLO_SPISU = "STAG"
SPIS_KDO_PRIRADI_CJ = "STAG"
SPIS_PR_RIZENI_CJ_UCHAZECE = "JEDNOTLIVE"
SPIS_KDO_PRIRADI_ID_PISEMNOSTI = "STAG"
SPIS_KDO_PRIRADI_ID_VYRAZENI = "STAG"
SPIS_PREFIX_CISLO_SPISU = prefix čísla spisu generovaného v IS/STAG. Jakýkoliv řetězec, který zajistí jedinečnost generovaných identifikátorů, např. "SA_" (jako "Studijní Agenda"). Čím kratší, tím lepší. Může být zcela prázdný/nevyplněný a ničemu to nevadí).
SPIS_PREFIX_ID_PISEMNOSTI = jako u čísla spisu, např. tedy "SA_". Opět - můžete nechat prázdný, ničemu to nevadí.
SPIS_PR_RIZENI_CISLO_SPISU = 'FAKULTA_AKROK'. (Budoucnost: Až proběhne domluva na druhou možnost, půjde to po konzultaci s vývojovým týmem IS/STAG změnit na 'JEDNOTLIVA_PRIHLASKA'.)
SPIS_UZAVRENI_SPISU_PO_DNU = Záleží plně na administrátorovi školy. Hodnota 0 (nebo pokud není parametr vůbec nastaven) znamená, že se spis studenta uzavírá okamžitě po uzavření studia studenta. Jakákoliv jiná hodnota udává počet dnů, po jehož uplynutí (od data ukončení studenta) se spis automaticky uzavře (toto uzavírání probíhá jednou denně v rámci pravidelné úlohy v noci)
SPIS_TELO_EMAILU_ST, SPIS_TELO_EMAILU_UCH - V případě vypravení písemností emailem může být v těchto parametrech uveden text, který bude spisovkou odeslán jako text onoho emailu. V příloze pak bude PDF s konkrétním dokumentem. Parametry lze dát až na úroveň fakulty.
SPIS_PROPOJENO = "A". Tento parametr nastavit až jako POSLEDNÍ věc konfigurace, tímto parametrem se propojení zapíná!

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 práci s chybami.

Číselníky IS/STAG

Konektor na tuto spisovku podporuje funkci stažení některých vybraných číselníků z API spisové služby. Toto můžete provést prostřednictvím portálu IS/STAG / Administrace / Externí systémy / Akce / tlačítko "Stažení číselníků spisovek v ZIP souboru". Získáte ZIP soubor s několika číselníky, jejichž hodnoty "ID" budete pro konfiguraci na straně IS/STAG potřebovat.

V IS/STAG je několik číselníků, které musejí být synchronizovány s číselníky použitými ve spisové službě. Jedná se o číselníky (domény). Zajistěte, že položky těchto číselníků budou mít stejné hodnoty i významy, jako mají adekvátní číselníky ve spisové službě:

SPIS_SKARTACNI_ZNAK, SPIS_SPISOVY_ZNAK, SPIS_DORUCOVACI_DESTA, ZPUSOB_VYRIZENI

V konektoru na tuto spisovou službu se tyto číselníky nijak nevyužívají. Tj. ve formulářích s nastavením tyto položky uvidíte, ale je naprosto jedno, jak a zda vůbec budou vyplněny. (tj. při migraci z BBM se tím nemusíte zabývat).

ZPUSOB_ODESLANI

Navrženo je to tak , abyste při přechodu z BBM spisovky mohli vzít svůj stávající číselník, na který jste zvyklí, nechat jeho položky (tedy jejich klíč a název) a pouze v okamžiku přechodu na novou spisovku vyměnit konfigurační hodnoty v atributech "pomocná hodnota 1, 2, 3". Možnost zadat v pomocné hodnotě 2 způsob odeslání v případě odeslání do zahraničí (jak bylo podporováno u BBM) byl zrušen, stejně se již tento problém léta řeší jinak. Ponovu je tedy třeba nakonfigurovat tento číselník tak, aby byl navázán na několik číselníků spisové služby Gordic (vše z toho je nutné, aby IS/STAG předával spisovce v okamžiku založení/odeslání písemnosti, proto to musí být vyplněno tak, jak to požaduje spisovka) a to takto:

Pomocná hodnota 1 "POM_HODNOTA" - odpovídá spisovkovému "způsobu doručení", musí obsahovat klíč z číselníku spisovky PrehledZpusobuDoruceni. Příklad hodnot: neurceno, posta, osobne, kuryr, dorucovaci sluzba, ds, ...
Pomocná hodnota 2 "POM_HODNOTA2" - odpovídá spisovkovému "druhu zasilky", musí obsahovat klíč z číselníku spisovky PrehledDruhuZasilky. Příklad hodnot: neurceno, balik, cenne psani, psani standard, doporucena zasilka, ...
Pomocná hodnota 3 "POM_HODNOTA3" - obsahuje-li hodnotu "ODESLANI_IHNED", znamená to, že má IS/STAG po dokončení písemnosti (tj. čeká-li se na PDF např. z el. podepisování, pak se to děje až když PDF dorazí a je přiloženo jako příloha) předat "režim odeslání" s hodnotou "odeslani" (což dle dokumentace spisovky znamená "Provést evidenci odeslání."). Pokud hodnota nastavena není, je spisovce předán režim "priprava" (což dle dokumentace spisovky znamená "Pouze příprava budoucího odeslání. Nezpracovává se předpis mailu/DZ! V detailu odeslání je pak zásilka ve stavu 'připravováno'. Režim přípravy nelze kombinovat s fyzickým odeslání mailu/DZ (způsob doručení 'ds' a 'elektronicka posta').").

Poznámka - vývojáři IS/STAG netuší, jaké kombinace různých hodnot číselníků spisovky jsou použitelné, jaké ne - musíte vyjít z vlastností a popisů spisovky. Nicméně i my jsme se snažili získat nějaké informace a zde máme sepsány informace, které jsme od Gordic spisovky získali:

Způsob doručení: "e-mail" je odeslání mailu přímo adresátovi.
Způsob doručení: "e-vypravna" je odeslání mailu adresátovi přes výpravnu, která musí potvrdit vypravení.
Způsob doručení: "ds" je odeslání datové zprávy přímo adresátovi.
Způsob doručení: "ds e-vypravna" je odeslání datové zprávy adresátovi přes výpravnu, která musí potvrdit vypravení.

Poznámka obecná: vývojáři IS/STAG nedostali žádné zadání týkající se toho, jaké způsoby odeslání školy používají, jak přesně jsou ve spisovce implementovány a tudíž ani netuší, co přesně mají mít připraveno/vyzkoušeno vůči nové spisovce. Od kolegů z Gordic jsme taktéž nedostali rozumný popis jejich API v tomto ohledu (ano, dostali jsme nějaké příklady, ale typicky vůbec neznáme význam některých položek, jejich kombinací a podobně). Proto je navržen číselník ZPUSOB_ODESLANI takto obecně. K ničemu "lepšímu" nemáme aktuálně žádné podklady ani zadání.

Poznámka: spisová služba bohužel vyžaduje, aby jí IS/STAG v případě odesílání e-mailem respektive datovou schránkou předával i zdrojovou e-mailovou adresu (jakoby adresu z níž to bude odesláno "From:") i zdrojovou datovou schránku (zřejmě datovku vaší organizace, ze které se to má odeslat). I přes konzultace s kolegy z Gordic toto musí být bohužel na straně STAGu nakonfigurováno a zároveň to musí odpovídat tomu, co je nastaveno ve spisovce. Proto jsou tyto dvě hodnoty potřebné a je třeba je mít v konfiguračním souboru viz. níže.

Budete-li potřebovat nějaké jiné možnosti při konfiguraci odesílání na spisovku Gordic, kontaktujte vývojové oddělení IS/STAG přes RT.

Řada čísel jednacích

S autory spisovky bylo dojednáno, že IS/STAG bude generovat všechny identifikátory včetně čísla jednacího - výhoda tohoto řešení je především v řádově rychlejším fungování celého propojení. IS/STAG totiž při vytváření písemnosti nemusí čekat na proběhnutí několika operací na straně spisovky, ale může celou tuto operaci provést na pozadí (stejně, jako tomu bylo v případě spisovky BBM). Nutnou podmínkou je však správná konfigurace na obou stranách.

Na straně IS/STAG:

Nadefinujte si právě jednu řadu čísel jednacích v SS0010, která bude přiřazena ke všem typům písemností. Definice této řady musí přesně odpovídat definici téhož na straně spisovky. Příklad pro VETUNI je řada generující ČJ v tomto formátu: "VETUNI-STAG/2024/1". Maska je tedy tato: "VETUNI-STAG/####/*"
Předpoklámě, že z doby BBM spisovky máte právě jednu řadu nadefinovanou - takže u ní pouze změňte tu "masku". STAG by měl začít generovat ihned novou a od jedničky. Nebudete tak muset tu řadu ČJ následně přidávat k typům písemností, když už to máte od BBM hotové.

Na straně spisovky:

Musíte mít nadefinován deník s názvem "STAGCJ", což je deník, v němž budou čísla jednací generovaná IS/STAGem.

Typy dokumentů v IS/STAG

Po nastavení číselníků je rovněž potřeba upravit nastavení jednotlivých typů dokumentů (tabulka SPIS_TYPY_DOKUMENTU, formulář SS0010) - u všech typů dokumentů nastavit především:

Platnost - zda se tento typ dokumentu do spisové služby vůbec vkládá
Způsob odeslání - výchozí hodnota, není-li pak uvedeno při vlastním odeslání jinak. Z číselníku ZPUSOB_ODESLANI.
Způsob vyřízení - nepoužívá se
Řada čísel jednacích - přiřaďte jednu definovanou řadu čj viz předchozí kapitola.
Identifikátor - Měl by obsahovat číselnou hodnotu (identifikátor) příslušného typu dokumentu, které jsou definovány ve spisovce v číselníku PrehledTypuDokumentu.
- POZOR, toto je zřejmě jediná položka od typu písemnosti, kterou budete muset měnit při přechodu na Gordic - používáte-li tedy vůbec mapování typů dokumentů na typy evidované ve spisovce...

Uživatelské identity

Je třeba vyplnit a udržovat tabulku s uživatelskými identitami, viz. kapitola na hlavní stránce o spisovkách. V případě spisovky Gordic se do "ID uživatele ve spisovce" vkládá "ID funkčního místa" ze spisovky (vývojáři IS/STAG nemají ponětí, jak vzniká a jak jej lze ve spisovce získat, nicméně je pro volání API nutný). Zároveň platí, že položky "ID spisového uzlu", "ID výpravny", "Místo", "Budova" jsou touto implementací zcela ignorovány a mohou zůstat nevyplněny. (Pokud by náhodou byly ve formuláři povinné, vyplňte tam libovolnou hodnotu, cokoliv, např. "xxx").

Ukončování spisů

V okamžiku ukončení studia (či případně po X dnech dle parametru SPIS_UZAVRENI_SPISU_PO_DNU ) volá IS/STAG v Gordic spisovce 2 operace:

Vyřízení spisu - parametrem tohoto vyřízení je "ID způsobu vyřízení spisu". Toto ID je možno nakonfigurovat v konfiguračním souboru viz níže. Pokud se vyřízení spisu nepodaří, je zapsána informace do IS/STAG logu komunikace s externími systémy a pokračuje se na další krok:
Uzavření spisu

Poznámka: Nastavení z formuláře SS0010 ze sekce "Ukončování spisů" se u implementace Gordic spisovky aktuálně ignoruje, používá se jedno globálně zadané "ID způsobu vyřízení spisu". Bude-li poptávka a jasné zadání, můžeme to zkusit opět (podobně jako bylo u spisovky BBM) uzavírání spisů "napasovat" na způsob ukončení studia.

Konfigurace modulu "Webové služby"

Do konfiguračního souboru nemusíte zapisovat nic přímo vy sami, pouze zjistěte potřebné hodnoty od dodavatele spisovky a předejte je supportu IS/STAG, doplníme je do konfigurace pro vás. Prohlédněte si níže jednotlivé položky a jejich komentáře a poptejte u dodavatele spisovky.

V konfiguračním souboru webových služeb (~/PORTAL-data/konfigurace/ws-config.properties) odkomentovat/připsat následující konfigurační parametry, ideálně až před konec souboru:

# ----------------------------------------------------------------------------------------
# ---------------------- Spisovka Gordic -------------------
# ----------------------------------------------------------------------------------------
# Nazev subsystemu: ess_gordic

# uzivatelske jmeno a heslo pro overeni sluzbou Gordic - jedna se o onoho jeidneho "super uzivatele", pod kterym IS/STAG ve spisovce operuje - Spisovka a adresa WSDL teto sluzby
ess_gordic_ws_username = XXX
ess_gordic_ws_password = XXX
ess_gordic_endpoint_ssl_url = https://ginis-test.vfu.cz/gordic/ginis/ws/ssl01stagtest/ssl.svc
ess_gordic_endpoint_gin_url = https://ginis-test.vfu.cz/gordic/ginis/ws/gin01stagtest/gin.svc

# ID "deniku" ve spisovce pri zakladani spisu
ess_gordic_denik_spis = XXX

# ID zpusobu vyrizeni spisu (pri ukoncovani spisu)
ess_gordic_zpusob_vyrizeni_spisu_id = XXX

# ID vlastnosti s kodem "UCHAZE" - oznacujeme si ji uchazecidno u pisemnosti uchazece
ess_gordic_id_vlastnosti_UCHAZE=XXX

# ID vlastnosti s kodem "CJIFIS" - ve spisovce BBM jsme oznacovali uchazecovo pisemnosti cislem jednacim - zde je importovana hodnota z BBM FISu
ess_gordic_id_vlastnosti_CJIFIS=XXX

# Zdrojova e-mailova adresa, z niz spisovka odesila pisemnosti e-mailem. Musi odpovidat adrese, ktera je nakonfigurovana ve spisovce
ess_gordic_src_email=XXX

# Zdrojova datova schranka, z niz spisovka odesila pisemnosti pres DS. Musi odpovidat adrese, ktera je nakonfigurovana ve spisovce
ess_gordic_src_ds=XXX

Hodnoty XXX nahradit příslušnými hodnotami podle domluvy s provozovateli spisovky.

Dále pak změnit hodnotu parametru spring.profiles.active - přidat (čárkou odděleně, pokud ještě není) hodnoty "esb" a "ess_gordic", čímž se funkcionalita propojení s touto spisovkou 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 = ..., esb, ess_gordic