Změny z pohledu DevOPS

Technická příručka pro upgrade zákaznické instance TAS z v5.17 na v5.19. Určeno DevOps a administrátorům, kteří upgrade plánují a provádějí: infrastruktura, konfigurace, databázové migrace, postup nasazení a rollback.

TL;DR – co vás nejpravděpodobněji shodí

Checklist

Proveďte dřív, než sáhnete na cokoliv dalšího.

Datové předpoklady migrací

Spusťte proti produkční kopii DB. Každý řádek ve výsledku znamená, že migrace spadne.

(A) JS_SCRIPTS.JS_TYPE – nově NOT NULL + check in ('C','F','R'), bez backfillu. Legacy default byl 'B'.

SELECT "JS_ID", "JS_TYPE" FROM "JS_SCRIPTS"
WHERE "JS_TYPE" IS NULL OR "JS_TYPE" NOT IN ('C','F','R');

(B) TEMPLATE_TASKS – nové CHECK constrainty.

SELECT DISTINCT "TTASK_TYPE"                FROM "TEMPLATE_TASKS";  -- povoleno: A,S,P,E,N,W,C
SELECT DISTINCT "TTASK_ASSESMENT_METHOD"    FROM "TEMPLATE_TASKS";  -- S,U,T,L,W,C,A,V,P
SELECT DISTINCT "TTASK_ASSESMENT_HIERARCHY" FROM "TEMPLATE_TASKS";  -- G,C,D,P,A,S,L
SELECT DISTINCT "TTASK_INVOKE_EVENT"        FROM "TEMPLATE_TASKS";  -- I,B
SELECT DISTINCT "TTASK_ENOT_TGT_TYPE"       FROM "TEMPLATE_TASKS";  -- O,G,T,P,S,U,R
--   totéž pro TTASK_ENOT_COPY_TYPE, TTASK_ENOT_BLIND_TYPE, TTASK_ENOT_REPLY_TYPE
SELECT DISTINCT "TTASK_CAN_BE_BUTTON", "TTASK_GEN_HISTORY",
       "TTASK_IS_BULK_COMPLETABLE", "TTASK_MULTIINSTANCE_FLAG",
       "TTASK_SUFFICIENT_END"               FROM "TEMPLATE_TASKS";  -- jen Y,N

(C) TEMPLATE_GRAPH

SELECT DISTINCT "TGRAPH_COLOR"     FROM "TEMPLATE_GRAPH";
--   povoleno: fffacd, e6e6fa, ffe4e1, f0ffff, ffe4b5, ffffff, '' 
--   (migrace hodnoty nejdřív zlowercasuje)
SELECT DISTINCT "TGRAPH_BPMN_TYPE" FROM "TEMPLATE_GRAPH";
--   povoleno: bpmn:UserTask, bpmn:SendTask, bpmn:ReceiveTask, bpmn:ServiceTask,
--             bpmn:SubProcess, bpmn:IntermediateThrowEvent, bpmn:IntermediateCatchEvent,
--             bpmn:ScriptTask, bpmn:Task, bpmn:Participant, bpmn:Lane

(D) Orphan procesy – migrace přidává FK INSTANCE_PROCESSES → TEMPLATE_PROCESSES. Orphanům sama nastaví TPROC_ID = NULL; zjistěte předem rozsah.

SELECT count(*) FROM "INSTANCE_PROCESSES" ip
WHERE ip."TPROC_ID" IS NOT NULL
  AND NOT EXISTS (SELECT 1 FROM "TEMPLATE_PROCESSES" tp WHERE tp."TPROC_ID" = ip."TPROC_ID");
--   totéž pro ARCH_INSTANCE_PROCESSES

(E) Odhad délky nejtěžších kroků

SELECT count(*) FROM "TEMPLATE_TASK_LINKS";            -- migrace #18 dělá UPDATE po řádcích
SELECT count(*) FROM "INSTANCE_PROCESS_HISTORY";       -- migrace #22 přetypovává date -> timestamp
SELECT count(*) FROM "ARCH_INSTANCE_PROCESS_HISTORY";  -- na MSSQL přes mezikrok nvarchar(max)
SELECT count(*) FROM "INSTANCE_TASKS";                 -- drop sloupců + validace CHECK
SELECT count(*) FROM "ARCH_INSTANCE_TASKS";

Blokery prostředí

Záloha

Migrace nevratně mažou data. Full backup DB je nutný – down() migrací obnovuje jen schéma, ne obsah.

Seznam objektů, které upgrade odstraní:

• CRON_RUNS – historie běhů cronů (přesunuta do Elasticsearche, stará data se nepřenášejí),
• GUIDES, HEALTH_STATUS_PARAM,
• INSTANCE_TASK_INVITATIONS, TEMPLATE_TASK_INVITATIONS,
• INSTANCE_TASK_LINKS, INSTANCE_LINK_CONDITIONS,
• INSTANCE_GRAPH, ARCH_INSTANCE_GRAPH,
• TEMPLATE_TASK_CALCULATIONS,
• sloupce: ITASK_SEEN, ITASK_DISC_FLAG, TTASK_DISC_FLAG, TTASK_ENOT_BODY, TTASK_IS_PROC_ID, TTJSCALC_TITLE, ITJSCALC_TITLE, TTASKLINK_IS_MANDATORY, IGRAPH_ITASKCON_ID, CRON_ALIAS, CRON_IS_CLONE, CRON_TIMEOUT, CRON_HELP.

Infrastruktura

Runtime a závislosti

Ani jeden package.json nemá pole engines – verzi Node určuje výhradně base image.

Nové backend závislosti: @modelcontextprotocol/sdk, @fastify/sse, fastify-plugin, tar-stream, tmp, tsx (dev).

Odstraněné: arangojs, typedi (nahrazeno vlastním DI v backend/src/infrastructure/di/service.ts), reflect-metadata, systeminformation, docx-templates, docxtemplater, pizzip (přesunuty do pluginu docxGenerator).

Frontend: ESLint + Prettier → Biome 2.4.x; přidán Vitest 4 + Testing Library + jsdom; react-beautiful-dnd → @dnd-kit; odstraněn hopscotch (zrušené Guides) a npm jako frontend dependency. Bezpečnostní bumpy: axios 1.16.1, sanitize-html 2.17.4, dompurify 3.4.5, express 4.22.2, lodash 4.18.1, overview-components 1.1.184. React / MUI / webpack majory beze změny.

Dockerfile

Backend (backend/Dockerfile)

• ARG TAS_APP_VERSION → ENV TAS_APP_VERSION zapečeno do každé stage. CI ho předává z git tagu (TAG_NAME_CLEANED, včetně prerelease suffixu).
• npm ci --legacy-peer-deps (kvůli openapi-typescript peer dep), v prod i dev stage.
• npm_config_allow_remote=root, npm_config_allow_git=root – npm 12 by jinak odmítl xlsx CDN tarball a git dependency annotpdf.
• Plugin source už není v backend build kontextu (backend/.dockerignore) a plugin_builder ho dostává přes named build context. plugin_builder nově dědí FROM test (dřív FROM linter).
• Unit testy se už při buildu nespouští (běží v samostatném CI jobu).
• Sada apk balíčků (LibreOffice, OpenJDK17, Chromium, msttcorefonts, openssl) je beze změny.
• Názvy produkčních targetů beze změny: prod, prod_obfuscated (default), prod_devlicense, prod_obfuscated_devlicense.

Kdo staví image ručně, musí použít:

docker buildx build --build-context plugin_source=./backend/plugin --target plugin_archives ...

Frontend (frontend/Dockerfile) – zkontrolujte deployment pipeline

Build se rozdělil podle licence. 5.17 měl source → prod / prod_obfuscated. 5.19 má:

source_base → source_prodlicense → prod, source_obfuscated_prodlicense → prod_obfuscated (default)
            → source_devlicense  → prod_devlicense, source_obfuscated_devlicense → prod_obfuscated_devlicencse

Build patchuje developmentBuild v frontend/src/components5.0/zustand/loggedUserStore.ts podle licence.

Nové a změněné env proměnné

Nově povinné

Odstraněné

Nové (všechny volitelné)

Mrtvá, ale stále deklarovaná

TAS_LOGGER_FILE_PATH zůstává v envVariables.ts, ale staticConfigHandler.ts ji už nečte (logging.fallbackfilePath z globalConfig.ts zmizelo). Nahradila ji TAS_LOGGER_SIEM_FILE_PATH.

Zpřísněná validace statické konfigurace – může odmítnout dosud fungující lokální override.

Frontend

Dynamická (GUI) konfigurace

Databázové migrace

24 nových logických migrací, každá jako dvojice MSSQL + PostgreSQL (žádná dialektově neutrální není). Plus regenerované snapshoty (.snapshot-TAS.json obou dialektů).

Přehled migrací

Migrace certifikátů do Vaultu (#3)

Migrace projde adresář process.env.TAS_CERTIFICATES_STORAGE_PATH (fallback /app/tas/storage/certificates), každý soubor v něm parsuje jako X.509, zašifruje a vloží jako secret_store řádek s kind = certificate.

Před migrací ověřte:

• že proměnná ukazuje na správný adresář a že je v běhovém prostředí migrace dostupný (volume namountovaný),
• že adresář obsahuje pouze certifikáty – cokoliv jiného (README, klíče, temp soubory) se pokusí naimportovat,
• že je inicializovaný globalThis.container (šifrovací klíč databáze) a existuje uživatel s id = 1.

Rozjezd secret_store.valid_from mezi 5.17 a 5.19

5.17 přidala sloupec migrací Migration20260528120000-secret-store-valid-from. Na 5.19 tato migrace neexistuje – sloupec přidává dřívější Migration20260424112724 (MSSQL) / …725 (PG).

Důsledky na DB, která už prošla 5.17:

• V migrační tabulce zůstane osiřelý záznam Migration20260528120000.
• Migration20260424112724/25 poběží „mimo pořadí“. Obě jsou psané defenzivně (MSSQL if not exists (select 1 from sys.columns …), PG add column if not exists), takže nespadnou – to je oprava tas-3673, která dřív končila MSSQL chybou 2705.
• PostgreSQL – typový rozjezd. 5.17 vytvořila valid_from jako timestamp, 5.19 by ho vytvořila jako timestamptz. Migrace sloupec přeskočí, takže zůstane timestamp a neodpovídá 5.19 snapshotu/entitě. Funkčně to zatím nevadí, ale příští migrace generovaná ze snapshotu to může chtít řešit. Po upgradu ověřte a případně ručně sjednoťte.
• breakpointCheck (npm run mig) může na osiřelý záznam upozornit – použijte npm run mig:nocheck nebo nové nástroje níže.

Nové CLI pro řešení problémů s migracemi

npm run db:migrations                 # JSON dump migrační tabulky: název, čas, co je pending
npm run db:migrations:set-state -- name=<Migration…> state=executed   # označí za provedenou (SQL se nespustí)
npm run db:migrations:set-state -- name=<Migration…> state=pending    # smaže řádek → poběží znovu

Další nové příkazy: npm run db:report (report fragmentace indexů + heavy queries), npm run db:rebuild-indexes.

Post-migrační krok mimo migrační tabulku

Každý migrate up nově spouští normalizaci parametrů cronů proti parametersSchema dané cron třídy:

• typové neshody se zkoumají a koerzují ("5" → 5),
• vlastnosti nepovolené schématem se odstraní,
• defaulty se nedoplňují,
• řádek, který ani po normalizaci nevalidoval (nebo se nepodařilo naparsovat), zůstane netknutý a zaloguje se warning.

Doporučený postup upgradu

1. Oznámení odstávky. Odhad okna podle dotazu (E) – migrace #14, #18, #19 a #22 jsou lineární v počtu řádků.
2. FULL BACKUP DB + snapshot volume se storage (certifikáty, pluginy, DMS).
3. Předletová kontrola datových předpokladů a blokerů prostředí. Datové vady opravit TEĎ.
4. Zastavit provoz:
   • nejdřív cron workery (nutné – cron overhaul je jednofázový drop sloupců),
   • pak web backendy,
   • frontend / LB do maintenance.
5. Připravit konfiguraci pro 5.19:
   • TAS_APP_VERSION (povinná),
   • odstranit TAS_LOGGER_ARANGO_* a TAS_LOGGER_ELASTIC_ENABLE,
   • ověřit TAS_CERTIFICATES_STORAGE_PATH pro migraci,
   • volitelně TAS_PLUGIN_STORE_URL na frontendu.
6. Nasadit 5.19 image (backend + frontend), backendy zatím NESTARTOVAT.
7. Spustit migrace z jedné instance: npm run mig. Sledovat log; při pádu neopakovat naslepo – viz nové CLI.
8. Zkontrolovat migrační log:
   • warningy z normalizace parametrů cronů,
   • řádky s tagem [tas-3432] = konfigurace smazaných EWS cronů → uložit stranou,
   • výsledek migrace certifikátů do secret_store.
9. Nasadit / aktualizovat pluginy na verze pro 5.19. Bez toho se nenačtou.
10. Nastartovat web backendy → ověřit /status/liveness, /status/readiness, /status/startup.
11. Nastartovat cron workery.
12. Provést post-upgrade konfiguraci.
13. Projít ověřovací checklist.
14. Sundat maintenance.

Post-upgrade konfigurace

Pluginy – povinné

Manifesty v 5.19 mají minimalCompatibleTasVersion: "5.19.0" a maximalCompatibleTasVersion: "5.19.999". Protože application.version je nově skutečná verze (dřív ji maskoval zastaralý manifest.json s 5.18.16), nekompatibilní plugin se tiše přeskočí.

Verze pluginů v 5.19:

Nové možnosti správy pluginů:

• Administrace → Pluginy → záložka Plugin Store (jen když je nastaveno TAS_PLUGIN_STORE_URL),
• POST /plugins/install – nahraje archiv do plugin volume; plugin se tím nenačte,
• DELETE /plugins/:sysname – odinstalace (smaže složku, restartRequired: true),
• POST /plugins/kill – broadcast přes Redis; každý backend (web i cron) si vyvolá SIGTERM na vlastní graceful-shutdown handler a orchestrátor ho nastartuje zpět,
• plugin se špatným manifestem nebo nenačitatelnou capability už neshodí start backendu – zaloguje se a přeskočí (tas-3545).

Crony – vyžaduje pozornost

Kompletní přestavba (tas-3500). Co udělat po upgradu:

1. Projít celý seznam cronů v Administraci → Crony. Přejmenování sloupců (CRON_NAME→DISPLAY_NAME, CRON_FILE→TECHNICAL_NAME, CRON_SYNTAX→TIMING, CRON_STATUS→IS_ACTIVE boolean) proběhlo v datech, ale ověřte, že jsou aktivní ty správné.
2. Historie běhů se ztratila – CRON_RUNS je dropnutá, nová historie jde do Elasticsearch indexu <integrations.elastic.index>-cron-runs (zakládá se automaticky přes iniESIndex, no-op při vypnutém ES indexování).
3. Klonované crony zanikly (CRON_ALIAS, CRON_IS_CLONE dropnuty). Alias se přemigroval do uživatelského názvu.
4. Per-cron timeout zanikl (CRON_TIMEOUT), stejně jako endpoint POST /cron-runs/kill a akce „zabít běh“. Zůstává crash recovery přes stale heartbeat a indikátor „běží mnohem déle než obvykle“.
5. Cron help zaniklo – dokumentace parametrů je teď v parametersSchema a renderuje ji JsonForms.
6. Nastavit application.crons.consecutiveFailureThreshold (default 5) – po N po sobě jdoucích selháních jde notifikační e-mail na chybové adresy cronu.
7. Zvážit aktivaci nových cronů (zakládají se ručně, defaultně neaktivní): DatabaseHealthReportCron, DatabaseIndexRebuildCron.
8. Cron DeleteLogs má nový výchozí název a popis („Remove old logs.“ – slovo „arango“ vypadlo).
9. „Tovární nastavení“ na detailu cronu teď resetuje bezpodmínečně (timing, popis, parametry i aktivní stav; uživatelský název zůstává).
10. Crony s parametry neodpovídajícími schématu už nelze uložit – POST /crons/create a POST /crons vrací 400 INVALID_CRON_PARAMETERS.
11. Změna chování: MailReportsCron počítá úkol jako po termínu při deadline < teď (dřív < dnešní půlnoc).

Zabbix – push → pull, nutná rekonfigurace

Kroky: vygenerovat API token s admin scope → naimportovat tas_template.yaml → nastavit makro → ověřit LLD discovery. Scrape endpoint záměrně obchází isAlive/inMaintenance hooky, takže monitoring funguje i během draining/maintenance.

Klíče tas.crons a tas.cronStatus a akce /health-status crons (cronStatus/crons/cronsGui/cronsHealth) si zachovaly tvar polí – stávající monitoring na ně funguje dál. Zrušeny: scheduledTasksGui, metrika tasZombieCron.

Odstraněná stránka Appstatus, nová System Health

Legacy stránka Appstatus je pryč. Nahrazuje ji Administrace → System Health (/administration/system-health) s probami pro: application, database, database-activity, Elasticsearch, Redis, Tika, LibreOffice, e-mail, Firebase, crony, host resources a business KPI.

• Fleet-aware: každá instance se vzorkuje po 60 s do Redis (HEALTH_FLEET hash + per-instance série, 48h okno / 49h TTL). Bez Redis degraduje na lokální instanci.
• Database Activity čte pg_stat_activity / sys.dm_exec_*. MSSQL uživatel potřebuje VIEW SERVER STATE, jinak se karta zobrazí jako „unknown“ (dřív by vypsala celý failující SQL).
• Nový dashboard widget „System health“ (admin only).

E-mail

• Nový transport msgraph (app-only / Client Credentials) vedle basic, oauth2 a sendmail.
• Vlastní X-hlavičky v notifikacích s podporou placeholderů + allowlist (TAS_MAIL_ALLOWED_CUSTOM_HEADERS).
• MS Graph mail crony: clientSecret může být {{vault:name}} odkaz na Vault secret; nová tlačítka „Discover folders“ (POST /ms-graph/discover-folders) a duplikace schránky.
• Nově zakládané crony „Create Processes from MS Graph mails“ mají useEmailObjectInDataHolder = false (aby field mapping fungoval). Stávající crony si drží uložené parametry.

Hesla a autentizace

• Hashování přešlo na argon2id s lazy migrací z bcryptu – uživatel se přehashuje při příštím přihlášení. Globální pepper byl zrušen, včetně souvisejícího configu.
• USERS.USER_PASSWORD rozšířen na 255 znaků.
• Fallback na jinou authority při výchozí (bez explicitního auth_id) cestě přihlášení.
• Zamčení uživatele nově invaliduje cache (USER2-<id>) → existující access tokeny přestanou fungovat okamžitě.
• GET /authorization/config vrací paramsSchema per authority (frontend renderuje formuláře z JSON schématu).

Breaking changes pro integrace a API

Odstraněné endpointy

Změněné kontrakty

Nové endpointy

• POST /mcp/:scenario? – stateless MCP Streamable HTTP endpoint pro externí klienty (Claude Desktop / Claude Code). Scénáře: case-creation, case-editing, case-lookup, knowledge, account, administration; holé /mcp vystaví vše. Jen API token (tokenPayload.kind === "api"), session token vrací UNAUTHORIZED. Každé volání se auditovává do AI_LLM_TOOL_CALL se source = mcp.
• GET /system-health, /system-health/series, /system-health/db-activity, POST /system-health/db-activity/cancel, GET /system-health/metrics
• GET /crons/available, GET /crons/monitor, POST /crons/create, /cron-runs, /cron-runs/:id
• GET /plugins/version, POST /plugins/install, POST /plugins/kill, DELETE /plugins/:sysname
• GET /plugin-config, /plugin-config/:sysname/schema, /plugin-config/:sysname/data, POST /plugin-config
• GET /scripts/list/:type, GET /scripts/mapped/:kind/:kindId?
• POST /ms-graph/discover-folders
• DELETE licence, vault key-pair generování, AI observability endpointy

Ověřovací checklist po upgradu

Start a základ

• Backend nastartoval bez "ENV variable … is mandatory" v logu
• GET /plugins/version vrací skutečnou verzi (5.19.x), ne 5.18.16
• /status/liveness, /status/readiness, /status/startup OK
• Administrace → System Health: všechny proby zelené nebo žluté, žádná v „unknown“ z důvodu chybějících práv

Pluginy

• Administrace → Pluginy: všechny očekávané pluginy jsou načtené (nekompatibilní se tiše přeskočí – porovnejte se seznamem verzí)
• helpDocs a docx-generator nainstalované, pokud je zákazník má mít
• KSeF: vyřešeno

Databáze a migrace

• npm run db:migrations – nic není pending, žádný nečekaný orphan kromě Migration20260528120000
• PostgreSQL: ověřen typ secret_store.valid_from
• Certifikáty: SELECT count(*) FROM secret_store WHERE kind = 'certificate' odpovídá počtu souborů v původním adresáři

Crony

• Seznam cronů odpovídá stavu před upgradem (aktivní / neaktivní, timing)
• V migračním logu žádné neopravené warningy z normalizace parametrů
• Cron monitor se plní; ES index <index>-cron-runs existuje
• EWS crony: konfigurace vytažená z logu [tas-3432], přenesená do MS Graph cronů
• Testovací ruční spuštění klíčových cronů (Run manually)

Logy a monitoring

• Logy tečou do Elasticsearche; žádná stopa po Arango konfiguraci
• Zabbix scrapuje GET /system-health/metrics, LLD discovery funguje
• Filtrování logů podle iproc_id / tproc_id / ttask_id / header_id / cron_id funguje

Frontend

• Ikony se zobrazují správně (tas-3710 – BOM v appStyles.css rozbíjel @font-face)
• Přihlášení, dashboard, přehledy, detail případu, workflow diagram
• Diagram případu (nový payload) se vykresluje včetně archivovaných případů

Funkční ověření

• Odeslání e-mailu (notifikace i report)
• Generování tisku / PDF (LibreOffice, Puppeteer/Chromium)
• Upload do DMS + fulltext + náhledy
• AD/LDAP synchronizace (AdSyncCron – v 5.19 opravena, dřív tiše nesynchronizovala nikoho)
• Šablony: uložení úkolu, uložení proměnné, uložení odkazu v diagramu
• Přihlášení uživatele s bcrypt heslem → ověřit rehash na argon2id

Poznámky ke škálování

• Restart pluginů (POST /plugins/kill) shodí všechny backendy sdílející Redis, včetně cron workerů, se staggerem. Deployment musí ukončené kontejnery automaticky startovat.
• Plugin volume (TAS_PLUGINS_LOCATION → featureFlag.plugins.destination) musí být nově zapisovatelný za běhu a sdílený všemi instancemi – instalace i odinstalace pluginů z GUI do něj zapisují.
• Instance se v Health page tagují jako Web nebo Cron worker; přepínač instancí je v hlavičce.
• Globální infra proby (DB / ES / Redis / Tika / mail / Firebase / crony / business) cachují výsledek v Redis na jedno vzorkovací okno, aby se při N instancích nespouštěly N krát.

Co konkrétně degraduje bez Redis (TAS_CACHE_MODE=memory):

CI proměnné (jen pro pipeline, ne runtime): PLUGIN_STORE_URL nahrazena dvojicí PLUGIN_STORE_DEV_URL / PLUGIN_STORE_PROD_URL (.github/workflows/image-tag-push.yml) – buildy z stable/* publikují do PROD storu, ostatní do DEV. Sdílené zůstávají secret CICD_PLUGIN_STORE_PRIVATE_KEY a proměnná PLUGIN_STORE_USERNAME (default tas-ci). Publikace je opt-in – dokud není URL nastavená, je to no-op.

Rollback

Migrace mažou tabulky a sloupce; down() obnoví jen strukturu, ne data. Praktický rollback je tedy:

1. Zastavit 5.19 (web i cron).
2. Obnovit DB ze zálohy pořízené v kroku 2 postupu upgradu.
3. Vrátit 5.17 image a původní env (vrátit TAS_CERTIFICATES_STORAGE_PATH do configu, případně Arango proměnné).
4. Vrátit pluginy ve verzích pro 5.17.
5. Vrátit původní Zabbix šablonu.