Seznam vstupních kontrol (validací) automatizovaných výstupů a chybových kódů Analytického modulu a obsahu potvrzovacího balíčku

Ministerstvo financí, odbor 73 – Procesní agendy a regulace hazardu v souvislosti s povinností provozovatelů poskytovat výkaznictví podle § 13a zákona č. 186/2016 Sb., o hazardních hrách, ve znění pozdějších předpisů, a za účelem snadnější implementace vyhlášky č. 10/2019 Sb. (dále jen „reportingová vyhláška“) zveřejňuje aktualizovaný seznam vstupních kontrol (validací) automatizovaných výstupů chybových kódů Analytického modulu AISG.

I. Obsah potvrzovacího balíčku

V případě, že při přijímání automatizovaného výstupu na úrovni komunikačního rozhraní došlo (prostřednictvím vstupních kontrol) k identifikaci nedostatků, obsahuje potvrzovací balíček podle § 3 odst. 3 reportingové vyhlášky jeden nebo více z následujících souborů:

• validation-report.csv - přehled validace jednotlivých CSV souborů balíčku
• validation-errors.csv - seznam nalezených jednotlivých chyb
• validation-processing.txt - detailní výpis zpracování balíčku

Dále v případě identifikace nedostatků v rámci databázových validací obsahuje potvrzovací balíček databázových validací jeden nebo více z následujících souborů:

• db-validation-report.csv - přehled validace jednotlivých CSV souborů balíčku
• db-validation-errors.csv - seznam nalezených jednotlivých chyb

Výstupní soubory z jednotlivých vrstev validací jsou pojmenovány odlišně a mají částečně odlišnou strukturu (ve výstupech komunikačního rozhraní odkazují na čísla řádků vstupních souborů, ve výstupech databázových validací na primární klíče).

Databázové validace umožňují přijetí balíčku s určitou mírou nekonzistencí a chyb. V takovém případě je součástí OK i ERR potvrzovacího balíčku neprázdný soubor db-validation-errors.csv, ve kterém se mohou objevit chyby označené jako „error“ nebo „warning“.

Vždy je tak třeba sledovat nejen návratový status potvrzovacího balíčku (OK/ERR), ale i obsah souboru db-validation-errors.csv.

V případě, že bylo přijetí automatizovaného výstupu odmítnuto (ERR potvrzovací balíček), měl by provozovatel na chybové hlášky „error“ v souboru db-validation-errors.csv reagovat a záznamy opravit. Pokud však byl automatizovaný výstup přijat (OK potvrzovací balíček), nepředpokládá se oprava těchto chyb v tomto automatizovaném výstupu. Provozovatel by však měl těmto chybám věnovat pozornost a nastavení svého systému upravit tak, aby se tyto chyby v dalších automatizovaných výstupech již nadále neobjevovaly.

Odpovědi typu „warning“ nevedou k odmítnutí přijetí automatizovaného výstupu, ale sdělují, že některé z provozovatelem poskytnutých záznamů v automatizovaném výstupu nesplnily podmínky validace (včetně uvedení chybové hlášky a specifikace, o jaké záznamy se jednalo). „Warning“ se však objevuje pouze u validací, u kterých je v okamžiku zpracování automatizovaného výstupu nastavena nulová váha, nejsou tedy při přijímání automatizovaného výstupu zohledněny a provozovatel na ně nemusí nijak reagovat. K těmto odpovědím dochází zpravidla z důvodu zpětného doplnění některých záznamů spadajících do jiného časového období v rámci činnosti spojené s opravou chyb ve dříve poskytnutých automatizovaných výstupech.

V souboru db-validation-errors.csv se nyní nezapisují všechny chyby. Z každého validovaného CSV souboru se do souboru zapisuje maximálně 100 000 řádků chyb. Každá jednotlivá chyba je uvedena na samostatném řádku.

II. Seznam vstupních kontrol (validací) automatizovaných výstupů a chybových kódů Analytického modulu

Soubor DQ_Kontroly_ver013 ( 84,73 kB) uvádí přehled validací (vstupních kontrol) a chybových kódů Analytického modulu AISG (implementace reportingové vyhlášky na straně orgánu vykonávajícího dozor) jako informaci pro provozovatele hazardních her upřesňující význam chyb v souboru validation-errors.csv potvrzovacího balíčku.

Záložka Columns

Záložka uvádí pro všechny položky uvedené v jednotlivých datových souborech jejich pořadí v záznamu, popis, vyžadovaný datový typ, pravidla pro nevyplnění a měnitelnost položek (nullable, changeable).

Ve sloupci foreign key scope je pro položky s datovým typem referenční vazba (D_REFERENCE) uvedeno pravidlo STG nebo PKG. Jedná se o cizí klíče do jiné tabulky. STG vyžaduje poskytnutí záznamu s primárním klíčem v totožném balíčku či balíčku v minulosti. PKG vyžaduje uvedení záznamu s primárním klíčem přímo v balíčku. Pravidlo PKG může být v některých odůvodněných případech dle rozhodnutí Ministerstva financí zmírněno (zpravidla dočasně) na nastavení STG. Uvedené se děje zpravidla v případech, kdy probíhají aktivity spojené s opravou chyb ve dříve poskytnutých automatizovaných výstupech.

Ve sloupci changeable jsou uvedena pravidla změn hodnot položek v opakovaně zaslaných záznamech, jak jsou zpravidla předvídaná reportingovou vyhláškou. Jednotlivá pole jsou klasifikována do skupin:

• NOT CHANGEABLE: Pole v daném řádku již bylo dříve vykázáno za některý předchozí časový slot a nesmí měnit svoji hodnotu. Kontrola validací: ERR_FIELD_CANNOT_CHANGE.
• NULL -> NOT NULL: V dřívějším balíčku poskytnutou neprázdnou hodnotu sloupce není možné měnit. Pole se může změnit z hodnoty NULL (lze poskytnout opakovaně) na hodnotu NOT NULL pouze jednou (v případě, že dojde ke změně hodnoty NULL položky záznamu z důvodu, že položka v okamžiku prvního poskytnutí záznamu nebyla známa, poskytne se celý záznam s aktuálními hodnotami znovu v automatizovaném výstupu pro vzdálený přístup, a to za období, kdy ke změně hodnoty položky záznamu došlo). Kontrola validací: ERR_FIELD_FILL_ONLY.
• NULL/NOT NULL -> NOT NULL: Jednou vyplněnou hodnotu sloupce lze pouze měnit, ale nelze ji vymazat (pravidlo NULL/NOT NULL -> NOT NULL). Pole se může změnit z hodnoty NULL/NOT NULL na hodnotu NOT NULL (v případě, že dojde ke změně hodnoty NULL položky záznamu z důvodu, že položka v okamžiku prvního poskytnutí záznamu nebyla známa, poskytne se celý záznam s aktuálními hodnotami znovu v automatizovaném výstupu pro vzdálený přístup, a to za období, kdy ke změně hodnoty položky záznamu došlo; pokud by nastala situace, kdy by došlo ke změně hodnoty NOT NULL položky, za účelem zajištění správnosti dat poskytne se celý záznam se změněnou (opravenou) hodnotou v položce). Kontrola validací: ERR_FIELD_FILL_OR_CHANGE.
• NULL/NOT NULL -> NULL/NOT NULL: pole se může změnit z hodnoty NULL/NOT NULL na hodnotu NULL/NOT NULL, u těchto položek jsou přípustné jakékoli změny

Záložka Data Quality checks

Záložka uvádí detailní seznam explicitně definovaných databázových validací (ve skupině „Aplikace DWH“), vázaných na jednotlivá pole tabulek. Definice jsou uvedeny formou pseudojazyka využívající operace popsané na záložce Operation a dodatečné podmínky uvedené ve sloupci Where clause.

Ve skupině „Aplikace DWH“ jsou kromě těchto explicitně definovaných validací prováděny i implicitní validace vycházející z datové struktury datového modelu.

Některé z výše uvedených typů validací mají jak implicitní instance, tak i další explicitně definované instance.

Záložka Domain Types

Záložka uvádí výčet využívaných datových typů a jejich parametrů.

Záložka Codelist entries

Záložka uvádí výčet číselník hodnot určených reportingovou vyhláškou.

Záložka Data Quality Types

Záložka uvádí všechny typy validací a příslušné chybové kódy.

Ve sloupci Kategorie validace je uvedena skupina validací, a to

• validace ve skupině "Komunikační rozhraní", které jsou vykonávány bezprostředně po stažení datového balíčku;
• validace ve skupině "Aplikace DWH", které jsou vykonávány v druhém kroku, a to za předpokladu, že jsou všechny validace Komunikačního rozhraní úspěšné.

Ve sloupci „Kód chybového hlášení“ je uveden příslušný chybový kód.

Změny validací (duben 2024)

Od 1. 1. 2024 došlo k účinnosti novely zákona o hazardních hrách. V návaznosti na tyto změny a vydaný metodický pokyn (zde) dochází k úpravě vstupních kontrol (validací) automatizovaných výstupů a chybových kódů Analytického modulu.

V souboru DQ_Kontroly_ver013 ( 84,73 kB) jsou zeleně podbarveny řádky, u kterých došlo ke změně oproti verzi011. Od dubna jde o následující:

1. Změny validací v návaznosti na zrušení dočasných kont

Novela zákona o hazardních hrách mění pravidla pro fungování uživatelských kont v dočasném režimu. Současně stanovuje jiná pravidla pro nutnost nastavení sebeomezujících opatření. Nová pravidla platí pouze pro uživatelská konta, která vznikla od 1. 1. 2024.

Na list Data Quality checks byly přidány nové validace Konto_Zmeny_5 a Sebeomezeni_18. Zároveň byly zpřesněny validace Sebeomezeni_4 a Sebeomezeni_6.  Nové i upravené validace jsou podbarveny zeleně.

Konto_Zmeny_5

Pravidlo:

Zrušení dočasných kont - od 1. 1. 2024 (včetně) nemůže vzniknout dočasné konto. Tj. všechna by měla být trvalá.

Nová byznysová validace, která nově bude kontrolovat hodnotu v tabulce konto_zmeny v položce TrvaleDocasne = T u uživatelských kont zřízených od 1. 1. 2024 (včetně).

Sebeomezeni_18

Pravidlo:

Žádné uživatelské konto nesmí být od 1. 1. 2024 zřízeno bez nastavení nebo odmítnutí sebeomezujícího opatření, tj. položka SOOdmitnuti musí být vždy vyplněna, a to u všech nově zřizovaných uživatelských kont od 1. 1. 2024 (včetně), i v případě postupu podle starého ZHH.

Hodnota sloupce Sebeomezeni.SOOdmitnuti musí mít vždy hodnotu vyplněnou (not_null) pro všechny záznamy Konto.Zrizenicas, které vznikly od 1. 1. 2024 (včetně).

Na základě těchto nových validací je nutné zaručit zpětnou kompatibilitu pro stávající validace. Následující validace jsou upraveny tak, aby se kontrola zaměřila pouze na konta s časem zřízení před 1. 1. 2024:

• Sebeomezeni_4
• Sebeomezeni_6

2. Nová kategorie hazardní hry „m“

Nově je doplněna do číselníků kategorií hazardní hry na list Codelist entries doplněna kategorie „m“, která znamená označení internetové živé hry, ve které účastníci hazardní hry hrají proti krupiérovi. Podbarveno zeleně. 

HraKategorie = m - internetová živá hra, ve které účastníci hazardní hry hrají proti krupiérovi

3. Změny validací v návaznosti na novou kategorii hazardní hry „m"

S ohledem na zavedení nové kategorie živé hry jsou nasazeny změny v těchto validacích (podbarveno zeleně na listu Data Quality checks):

• Evidence_Her_4
• HraToky_4
• HraToky_40
• HraToky_8
• HraToky_19
• JednaHra_1
• JednaHra_2
• JednaHra_8
• JednaHra_10

Drobné formulační změny byly také provedeny v šablonách pro generování zpráv o chybách ve validacích (list Data Quality checks, sloupec Description):

• ERR_FIELD_INVALID_COMBINATION
• ERR_FIELD_INVALID_INTEGRITY_WITHIN_PKG
• ERR_FIELD_SPECIFIC_ERROR_WITHIN_HISTORY
• ERR_FIELD_FILL_ONLY
• ERR_FIELD_FILL_OR_CHANGE

Tolerance k chybám

Na produkčním (ostrém) prostředí je nyní nastavena určitá míra tolerance k chybám v rámci databázových kontrol (s výjimkou implicitních validací, tj. zejména validací referenční integrity dat). Ministerstvo financí upozorňuje, že společně s nasazením výše uvedených změn validací dojde současně ke zpřísnění míry tolerance u některých souvisejících validací.

Shodná míra tolerance k chybám bude předem nastavena na veřejném testovacím prostředí (Playground), kde bude možné otestovat, zda by byl automatizovaný výstup po nasazení zpřísněné míry tolerance k chybám přijat.

Změny validací (srpen 2024)

V návaznosti na objevující se nekonzistence dat u některých datových souborů při poskytování výkaznictví budou při přijímání balíčku nově nasazeny níže uvedené validační kontroly a změny.

V souboru DQ_Kontroly_ver013 ( 84,73 kB) jsou zeleně podbarveny řádky, u kterých došlo ke změně oproti verzi011. Od srpna jde o následující:

1. Záložka Data Quality checks

Přidání nových validací:

• HraToky_42
• HraToky_43
• HraToky_44
• HraToky_45
• HraToky_46
• HraToky_47
• HraTokyKursova_15
• Prilezitost_8
• Prilezitost_9
• HraTokyKursova_16 (nahrazuje zrušenou validaci HraTokyKursova_4, jelikož ZHH umožňuje v některých případech přijetí cash-out i v případě solo sázky.)

2. Záložka Columns

Ve sloupci changeable jsou uvedena pravidla změn hodnot položek v opakovaně zaslaných záznamech. 

Změna pravidla z "NULL -> NOT NULL" na "NULL/NOT NULL -> NOT NULL" pro položku UkonceniCas v datovém souboru Preruseni_Omezeni_Kursova_Toto z důvodu možnosti opravovat data na základě nové validace Prilezitost_9.

Nasazení změn

Termín nasazení na testovací prostředí (Playground) – 1. 8. 2024
Termín nasazení na produkční prostředí -  12. 9. 2024

Materiály jsou poskytovány pro volné použití provozovatelů hazardních her jako pomocný nástroj pro usnadnění přípravy automatizovaných výstupů, jsou poskytovány bez záruky funkčnosti a nenahrazují normativní znění reportingové vyhlášky. Případné chyby a odlišnosti od normativního znění vyhlášky mohou být opraveny a publikovány stejným způsobem.