Crony v5.19

Crony jsou naplánované úlohy, které v TAS zajišťují běh workflow v čase (spouštění naplánovaných procesů, aktivace časovaných úkolů), rozesílku notifikací, údržbu dat a integrace s okolními systémy. Tento článek popisuje, jak crony ve verzi TAS 5.19 fungují, kde se spravují a jak se konfigurují, a obsahuje kompletní přehled všech 28 platformních cronů včetně doporučení, které z nich mít na instanci aktivní.

Související článek: Stav systému – Monitor cronů

1. Jak crony v TAS fungují

1.1 Kde je v administraci najdete

1.2 Architektura

• Crony neběží ve web-backendu, ale v samostatném procesu cron worker. Cron workerů může běžet víc současně – ve Stavu systému je poznáte podle typu backendu Cron.
• Každý cron je třída se čtyřmi povinnými poli:
  • schedule – výchozí cron výraz,
  • alias – výchozí zobrazovaný název,
  • description – výchozí popis,
  • defaultStatus – A / N (viz 1.4),
  • volitelně parametersSchema – JSON schéma, ze kterého administrace generuje formulář parametrů.
• Registr platformních cronů obsahuje ve verzi 5.19 přesně 28 položek. Plugin crony by se do stejného registru přimíchaly z nainstalovaných pluginů.
• Historie běhů se ukládá do Elasticsearch (index z TAS_ELASTIC_CRON_RUN_INDEX_NAME, ve výchozím stavu hlavní index s příponou -cron-runs). Zápis historie je jen observabilita, ne funkční stav – výpadek Elasticsearch nezastaví vykonávání cronů, jen se neuloží záznam o běhu. Autoritativní záznam o posledním běhu je krátký otisk v Redisu.
• Heartbeat monitor detekuje zaseknutý nebo spadlý běh: worker pravidelně hlásí, že cron žije, a po vypršení timeoutu se běh označí jako Zabitý (Process crashed (stale heartbeat).). Časování se řídí env proměnnými v kapitole 1.7.
• Souběh na víc workerech hlídá distribuovaný zámek v Redisu.
• Ke každému běhu se zaznamenává stav (R běžící, F dokončený, E chyba, K zabitý) a spouštěč (SCHEDULED / MANUAL).

1.3 Vytvoření záznamu ≠ instalace kódu

Toto je nejčastější zdroj nedorozumění:

• Třída cronu existuje v kódu vždy. Nedá se „doinstalovat“ ani „odinstalovat“.
• Admin z třídy v UI vytvoří pojmenovaný záznam v tabulce CRONS – teprve ten má vlastní rozvrh, parametry a příznak aktivní/neaktivní.
• Dokud pro cron neexistuje aktivní záznam, úloha se nikdy nespustí.
• U některých cronů dává smysl vytvořit víc záznamů (jeden na každou schránku, import, účet) – viz 2.7.
• Název záznamu (DISPLAY_NAME) musí být v rámci instance unikátní.

1.4 Výchozí stav a předpřipravené crony

Pole defaultStatus v kódu neznamená, že cron po instalaci běží. Znamená jen, že dialog „Přidat cron“ předvyplní přepínač aktivní.

Na čerstvé instalaci navíc seed migrace založí 9 záznamů – a to všechny neaktivní (IS_ACTIVE = false). Migrace vkládá data pouze tehdy, je-li tabulka CRONS prázdná, takže existující instance se upgradem nezmění.

Předseedovaná devítka je shodná s devíti crony, které mají defaultStatus = A:

• AdSyncCron
• CompetenceGeneratorCron
• iDokladSynchronizationCron
• MsGraphCreateProcessesFromMailCron
• MsGraphCheckUnprocessedMailsCron
• PhotosCleanupCron
• RunProcess
• TemplateProcessShredding
• XMLProcessImportCron

1.5 Formát rozvrhu

Cron výraz má v TAS 6 polí – oproti běžnému unixovému cronu je navíc pole sekund:

sekunda  minuta  hodina  den-v-měsíci  měsíc  den-v-týdnu
  0-59     0-59    0-23       1-31      1-12   0-6 (0 = neděle)

Formulář v administraci výraz kontroluje a neplatný odmítne hláškou Neplatná syntaxe cronu; zároveň pod polem ukazuje čitelný popis rozvrhu – ten si vždy přečtěte, je to nejrychlejší kontrola překlepu.

1.6 Co umí obrazovka Crony (5.19)

Verze 5.19 přinesla proti starším verzím několik novinek, které stojí za to znát:

• Technický název je sloupec v přehledu a dá se podle něj filtrovat (technický název = třída, kterou plánovač skutečně spouští).
• Aktivovat / Deaktivovat přímo z tříteckového menu řádku, bez otevírání detailu.
• Import / Export definice cronu jako JSON (tlačítko v detailu). Slouží k přenosu konfigurace mezi prostředími. Import cizího technického názvu je odmítnut.
• Logy – tlačítko v hlavičce detailu otevře prohlížeč logů omezený na daný cron.
• Tovární nastavení – obnoví rozvrh, popis, parametry i příznak aktivity z výchozích hodnot třídy. Uživatelsky zadaný název zůstane zachován. (Ve starších verzích reset u již nakonfigurovaného cronu nedělal nic.)
• Terminovat crony – pošle všem cron workerům pokyn ke korektnímu ukončení. Běžící úlohy se nechají dokončit, takže v pracovní době může operace zpracování zdržet.
• U MS Graph cronů: Discover folders (živé procházení stromu složek schránky přes Microsoft Graph, včetně převzetí ID složky do konfigurace) a možnost uložit clientSecret jako odkaz do trezoru ve tvaru {{vault:název}} místo otevřeného textu.

1.7 Globální konfigurace cronů

Nastavuje se přes env proměnné (statická konfigurace), případně přes dynamickou konfiguraci v application.crons.

Dále v dynamické konfiguraci application.crons:

Na tyto adresy chodí dva druhy upozornění:

1.8 Indikátory v Monitoru cronů

Monitor ve výchozím stavu zobrazuje jen aktivní crony; neaktivní se přidají přepínačem Zobrazit neaktivní. Crony si lze označit hvězdičkou jako oblíbené (ukládá se per uživatel) a připnout je tak na začátek seznamu. Statistiky (úspěšnost, průměrné trvání) se počítají za zvolené období: 1 h, 8 h, 1 den (výchozí), 3 dny, 1 týden, vše. Tlačítko „i“ otevře nápovědu k indikátorům.

2. Kompletní přehled cronů (TAS 5.19)

Sloupec Stav: A = dialog „Přidat cron“ předvyplní aktivní, N = předvyplní neaktivní. Ani jedno neznamená, že cron po instalaci běží (viz 1.4). Rozvrh i stav lze při zakládání libovolně přepsat.

2.1 Jádro plánování a workflow

Parametry PostponedTaskCron:

2.2 Pošta a notifikace

Parametry MailUsageStatisticsCron:

Parametry B2bAndSecretStoreValidationCron:

2.3 Údržba dat a úložiště

Parametry DeleteLogs (dny retence):

Cron si chybějící hodnoty doplní z výchozích, takže funguje i s prázdnými parametry.

Parametry CleanupCron:

• cleanupTmp (výchozí true) – smaže a znovu vytvoří dočasné podadresáře. Doporučeno ponechat zapnuté.
• tables – pole položek { name, keepDays, limit, processStatuses? }.

Výchozí sada tabulek:

Parametry DmsFileIndexingCron: errored (false), current (true), reindexAll (nenastaveno), maxIndexedFiles (nenastaveno = neomezeně), blockedRuntimeHours ([] – hodiny, ve kterých se běh ukončí chybou, aby indexace nezasahovala do provozu), indexingConcurrency (1).

2.4 Databáze a infrastruktura

• Parametry ElasticsearchIndicesCleanupCron: maxIndexSize ("15gb"), targetSize ("12gb"). Relevantní jen při logging.loggerType = "elastic".
• Parametry DatabaseHealthReportCron (všechny povinné): pageCountThreshold (1000), fragmentationThreshold (30 %), heavyQueryLimit (50).
• Parametry DatabaseIndexRebuildCron (všechny povinné): pageCountThreshold (1000), fragmentationThreshold (30 %), indexRebuildTimeoutInSeconds (120, jen PostgreSQL).

2.5 Bezpečnost, role a práva

• AdSyncCron zpracovává pouze autority s AUTH_MODULE = 'ldap' a AUTH_SYNC_ENABLED = 'Y'. Bez nakonfigurované LDAP autority se synchronizací tedy neudělá nic – je bezpečný i na instanci bez AD.
• Parametry CompetenceGeneratorCron: rebuildIndexesAfterGenerating (true), forceRebuildForAllCompetences (false).

2.6 Statistiky a intranet

2.7 Integrace – konfigurovatelné šablony

Tyto crony se nezapínají globálně. Admin z nich typicky vytvoří jeden pojmenovaný záznam pro každý konkrétní případ použití (jiná schránka, jiný zdroj XML, jiný účet), s vlastním rozvrhem a parametry.

RunProcess – parametr items[]: header_id (ID šablony), iproc_name (název případu), user_id (zakladatel, Admin = 1), orgstr_id (organizační jednotka, Root = 1).

iDokladSynchronizationCron – parametrem je pole konfigurací (clientId, clientSecret, dynamicTableIdentificator, mapping, pairBy – výchozí documentNumber, includeCreditNotes, includeProformaInvoices). Předseedovaná konfigurace má prázdné přihlašovací údaje, takže cron bez doplnění nic neudělá.

XMLProcessImportCron – parametr items[] s cestou k XML, mapováním na šablonu a proměnné, chováním ke zdrojovým souborům a limity. Jeden záznam zvládne víc konfigurací v poli items.

MS Graph crony – konfigurace je per schránka (autentizace, vstupní a výstupní složka, mapování polí e-mailu na proměnné, práce s přílohami, souhrnné a chybové e-maily). V 5.19 platí:

• Jedna rozbitá schránka nebo jeden rozbitý e-mail už neshodí celý běh – zpracovávají se izolovaně a běh pošle jeden souhrnný e-mail [MS-GRAPH - FAILED].
• Zpracovávají se jen zprávy, jejichž MAPI třída odpovídá povolenému prefixu (výchozí IPM.Note) – pozvánky, doručenky a odpovědi mimo kancelář se přesunou do výstupní složky bez založení případu.
• attachEmailAsPdf (výchozí vypnuto) připojí e-mail k případu jako PDF v jazyce aplikace.
• U nově zakládaných cronů je useEmailObjectInDataHolder nastaveno na false, aby se mapování polí skutečně projevilo.
• Parametr amountOfEmailByRun (předseedováno 100) omezuje počet e-mailů na jeden běh.
• MsGraphCheckUnprocessedMailsCron používá parametr numberOfDays (předseedováno 7) a měl by mít stejná pravidla schránek jako importní cron, jinak bude hlásit falešné nálezy.

3. Doporučení – které crony mít nainstalované

„Nainstalovaný“ cron = existující a aktivní záznam v Administrace → Crony. Připomínáme, že po čerstvé instalaci TAS 5.19 neběží žádný cron – devět jich má založený záznam, ale všechny neaktivní, zbylých devatenáct nemá ani záznam.

3.1 Nutné minimum – aktivujte prakticky vždy

Bez těchto přicházíte o základní funkčnost workflow enginu, nebo vám neomezeně roste úložiště. Ani jeden z nich přitom není po instalaci připraven.

3.2 Bezpečné nechat aktivní, i když je zatím nevyužíváte

Tyto crony jsou bez odpovídající konfigurace neškodné (nic nenajdou, nic neudělají), takže je můžete zapnout dopředu.

3.3 Zapněte jen podle skutečně používaných funkcí

3.4 Databázová údržba – opatrně

• Run database health report – doporučeno zapnout na produkci. Pouze čte, nic nemění, a dá vám podklad pro rozhodnutí.
• Run database index rebuild – nezapínejte naslepo. Aktivně přestavuje indexy a může výrazně zatížit databázový server.

3.5 Integrace – zakládejte cíleně, ne plošně

RunProcess, XMLProcessImportCron, iDokladSynchronizationCron a oba MS Graph crony se nezapínají jako celek. Založte pojmenovaný záznam přímo pro konkrétní integraci a nastavte mu vlastní rozvrh.

• Předseedované záznamy těchto cronů mají prázdnou nebo ukázkovou konfiguraci. Buď je doplňte, nebo je nechte neaktivní – aktivní záznam s neúplnou konfigurací sice nic nerozbije, ale zbytečně běží a plní log varováními.
• U RunProcess vždy přepište rozvrh – výchozí * * * * * * je každou sekundu.
• Oba MS Graph crony nastavte se shodnými pravidly schránek, jinak kontrolní cron hlásí falešné nálezy.
• Pro clientSecret použijte odkaz do trezoru {{vault:název}} místo otevřeného textu – zejména proto, že export definice cronu obsahuje hesla v čitelné podobě.

3.6 Doporučená konfigurace prostředí

Nezávisle na jednotlivých cronech nastavte:

1. application.crons.sendErrorMailAddresses a msGraphErrorMailAddresses na vlastní adresy (výchozí error@teamassistant.cz je adresa dodavatele).
2. TAS_CRONS_CONSECUTIVE_FAILURE_THRESHOLD explicitně, pokud vám záleží na citlivosti upozornění (efektivní výchozí hodnota je 5).
3. Ověřte, že běží alespoň jeden cron worker – ve Stavu systému musí být vidět backend typu Cron – a že TAS_CRONS_RUN_ON_START není false.
4. Provozujete-li víc cron workerů, zajistěte Redis (cache.mode = "redis"). Bez něj neplatí ochrana proti dvojímu spuštění téhož cronu.
5. Zajistěte, že cron workery mají automatický restart (restart policy). Aplikace je po ukončení sama nenastartuje.
6. Spusťte migraci Elasticsearch, jinak nebude k dispozici historie běhů ani statistiky v Monitoru.

4. Kontrola po instalaci nebo upgradu

1. Administrace → Crony – projděte seznam a ověřte, že crony z kapitoly 3.1 Nutné minimum mají založený a aktivní záznam. Po čerstvé instalaci je musíte založit nebo aktivovat ručně.
2. Monitor cronů – přepněte na Zobrazit neaktivní, zkontrolujte, že žádný aktivní cron nemá červený stav, nízkou úspěšnost ani varování overdue.
3. Parametry – u cronů s výchozími adresami dodavatele (MailUsageStatisticsCron, B2bAndSecretStoreValidationCron) a u retenčních pravidel (DeleteLogs, CleanupCron) projděte hodnoty a upravte je podle reálných požadavků instance.
4. Rozvrhy – u PhotosCleanupCron a RunProcess ověřte, že rozvrh není ponechán na výchozí „každou sekundu“.
5. Po upgradu z verze starší než 5.19 – migrace normalizuje uložené parametry proti schématům cronů. Každý přepsaný záznam zapíše varování s původním a novým JSON.

5. Řešení potíží