Běh akcí na aplikačním serveru a diagnostika chyb

Akce provozovaná jako služba je posloupnost XSLT transformací definovaná v settings.mxl. Některé transformace vytvářejí požadavky interního XML protokolu, server je provádí a jejich odpovědi poskytuje dalším transformacím. Chybová šablona může číst parametry z C++ i své vstupní XML. Podrobnosti z odpovědi předchozího požadavku tedy nemusí být nejprve převedeny na parametr, aby se mohly objevit ve výsledném Faultu.

Stránka je určena implementátorům akcí a vývojářům serveru. Zachycuje stav zjištěný 14. 10. 2026. Rozlišuje dokumentovaný koncept, ověřený tok zdrojového kódu, aplikační vzorek šablon a návrhy dalších změn. Nejde o potvrzení verze konkrétní produkční binárky ani o určení příčiny jednoho konkrétního běhu.

Z čeho akce sestává

Vrstva	Úloha
Registr akcí	Ověřuje dostupnost služby uživateli a roli, určuje aktuální build a případné zastupování. Samotná složka s XSL nestačí.
Build akce	settings.mxl, extract-soap.xsl, substepové XSL, případně místní soap-error.xsl a popis služby.
Společné transformace	Výchozí cesta [web:]/shared/actions/_transforms/; mohou být importovány buildem.
Soaps	Dispatcher, kontrola registru, cache definic, výběr služby a obecná chybová cesta.
Soaps::Soap	Načtená definice jedné akce a její vykonání.
Step, SubStep, Input, SoapData	Vnořené typy Soaps::Soap: pořadí transformací, nastavení, odkazy na vstupy a uložené výsledky.
XSLTs, XSLT, Transform	Cache kompilovaných šablon a transformační procesor MSXML 6.
Structure::solveQuery	Provádí interní požadavky vytvořené substepem s send="true".

Název služby se nemusí shodovat se složkou: např. zpracovani_platby_4512 může ukazovat na zpracovani-platby-4512/2014-06-25_08-40-48-763_1/. Viz existence služby a umístění popisu.

Soaps::DBTest volá proceduru prtestsoap s parametry název, role, uživatel. Generovaná procedura kromě aktivní akce, serverového prostředí a omezení uživatelů/rolí kontroluje časovou platnost. Vrací složku a případnou identitu pro zastupování. Názvy tabulek a sloupců se skládají z DAD; dokumentované xactrgs a sttn_trnfld jsou konkrétní realizací, nikoli pevnými názvy v C++.

Odkud se akce spouští

Vstup	Napojení na společné jádro	Doložené místo
HTTP SOAP	/soap/service/jmeno, /soap/table/jmeno, /soap/form/jmeno; form vybírá temp-form.	webserver.cpp:10–39, 2896, 3803
HTTP API	Parser /api/2.0/... vytvoří REST variantu SoapQuery; formáty a URL parametry zpracuje akce.	webserver.cpp:10–39; engine.cpp:28169–28509
XML požadavek action	Vytvoří interní HTTPQuery, předá obsah dispatcheru a vloží odpověď do <action>.	engine.cpp:1325–1339; action
Plánovaná akce	JobAction::execute ověří uživatele a volá dad->soap.	cron.cpp:918–1031; do-action
Uzly po změnách dokumentů	performNodes sestaví act:run-action, případně pdk-list, a předá SoapRequest do vlákna nebo seznamu volání.	engine.cpp:8869–9039
Synchronizace pošty	IMAPMainFolder::syncNew a syncChange sestaví poštovní SOAP a službu volají přímo s identitou synchronizace.	mail.cpp:2389–2490
Přihlašovací služby	OAuth a další autentizační cesty také volají dad->soap.	webserver.cpp:1750, 2495

Interní cesty nemusí provádět HTTP volání přes síť. Sdílejí dispatcher, ale liší se identitou, rolí, logem a převzetím výsledku. /soap/protocol má zvláštní univerzální větev: společné extract-soap.xsl → solveQuery → final-soap.xsl; neprovádí substepový build pojmenované akce.

JobService v tomto kódu ovládá serverové subsystémy příkazy Stop/Pause/Continue apod.; neznamená plánované volání transformační služby. K tomu slouží JobAction.

Celý průběh pojmenované akce

HTTP / action / pošta / plánovač / uzel
  → Soaps::operator()
  → registr + identita + role + dostupný typ volání
  → načtení nebo cache buildu a XSL
  → normalizace vstupního formátu
  → extract-soap.xsl                         výsledek 0
  → composeInput → XSL substep               výsledek x-y
      → při send=true: solveQuery → response výsledek x-y
      → kontroly prázdnosti, statusu, odpovědi
  → poslední substep → convertOutput
  → odpověď nebo chybová XSL → SOAP/JSON/HTTP výstup

1. Soaps::load kontroluje registr i při nalezení akce v cache. Změna složky buildu způsobí přenačtení nastavení. Podklady se neodvozují jen z názvu URL.
2. Soap::load zařadí do běhu pouze action-step obsahující substep. Tyto kroky tvoří samostatné číslování od jedničky; zadávací kroky bez substepů se nepočítají.
3. Podle verify-input-for se přijímá SOAP/XML/JSON/CSV/text/formulářový či jiný podporovaný vstup. Bez atributu je výchozí SOAP-only cesta. Vnitřní zpracování pracuje s XML; ostatní formáty dostanou XML reprezentaci.
4. Nultá transformace extract-soap.xsl vytvoří vstup pro další kroky a její výsledek se uloží jako zero. U table, form a některých REST volání se z něj získají parametry pro následující XSL.
5. composeInput spojí vybrané výsledky pod <input>…</input>. V tomto kódu nepřidává XML deklaraci. input/@from může být 0 (nultý výsledek), x-y (dřívější krok a substep od jedničky) nebo content (vnitřní XML příslušného input v nastavení). Více vstupů se spojí v uvedeném pořadí.
6. Substep transformuje vstup pomocí temp, pro formulářové volání pomocí temp-form. Deklarované XSL parametry získávají hodnoty z parametrů nastavení a aktuálního volání.
7. U nefinálního substepu se kontroluje prázdnost a případně status. Při send="true" se výstup parsuje jako požadavek a provede solveQuery. Uloženým výsledkem substepu je pak odpověď serveru, nikoli odeslaný požadavek. Standardně je obalená <response>; remove-from-response obal mění.
8. Výsledek se uloží do results[i][j]. Následující substep jej musí uvést jako vstup; celou historii akce nedostává automaticky.
9. Poslední substep má zvláštní větev: po kontrole velikosti jeho výstup pokračuje přímo do convertOutput. Běžná kontrola statusu, prázdnosti a provedení send z nefinální větve se zde neuplatní. Kontrolní substep proto musí být před posledním substepem.

sync="true" serializuje přístup k načtené akci přes její zámek; neoznačuje IMAP synchronizaci. Další souběh ovlivňují one-and-only, způsob spouštění uzlů a validátor unique-pdklist. Soap::solve nevytváří automaticky jednu společnou databázovou transakci přes všechny substepy. Transakční pravidla se posuzují v konkrétních odeslaných požadavcích a kontextu volání.

Co chybová šablona skutečně dostává

Soap::Error a Soaps::Error nastavují globální XSL parametry:

Parametr	Význam v prozkoumaném kódu
Code	Sender nebo Receiver podle chybové větve.
Reason	Text stanovený volajícím C++ nebo obecný důvod z Transform::getReason; při NULL se nenastaví.
Detail	Hodnota dodaná volajícím. getDetail() vrací jméno XSL relativní k webrootu nebo No template loaded.; jiné větve sem dávají např. jméno akce nebo chybu URL parametrů.
protocolFormat	Detekovaný vstupní formát, např. soap, xml, json.
Format	Volba error-format akce, pokud byla nastavena.

Současně procesor dostane vstupní dokument. Ten není obsahem parametru Detail. Rozhoduje konkrétní buffer předaný chybovým bodem:

Chybový bod	Vstup chybové XSL	Reason / Detail	Místo v engine.cpp
Selhání nulté transformace	Původní tělo; může být neplatné XML nebo jiný formát.	Obecný důvod / detail transformace.	28740–28747
Nultý status error nebo prázdný výstup	Výstup nulté transformace.	Důvod / detail transformace.	28529–28532
Prázdný nefinální výstup	Výstup transformace.	Transformation output is empty. / detail transformace.	28610–28627
Statusová kontrola selže	Výstup kontrolní transformace.	Transformation output check failed. / detail transformace.	28630–28638
Výstup nejde parsovat jako požadavek	Znovu sestavený vstup substepu, nikoli vadný výstup.	Parsing of transformation output failed. / detail transformace.	28698–28705
Odpověď požadavku obsahuje chybu	Celá odpověď in, včetně protokolových chyb.	Server response contains an error. / detail transformace.	28685–28694
Obecné selhání substepu	Sestavené <input>…</input>, případně s odpověďmi předchozích požadavků.	getReason() / getDetail().	28718–28736
Výstup přesáhl velikost	Umělé <error size="…"/>; původní výstup je odstraněn.	Transformation output is too large. / detail transformace.	28517–28527, 28585–28598
Selhání vyříznutí SOAP/XML při převodu	Převáděný výstup.	Something failed. / NULL.	28848–28870, 28899–28919
Selhání JSON převodu	Převáděný výstup.	Conversion to JSON failed. / NULL.	28874–28895

Protokolové chyby mají různé formy: @type='error', @status='error', uzel error, atributy detail, details, descr, text uzlu nebo vnořený SOAP Fault. LogMsg::toXML zapisuje také number a severity. Samotné jméno error tedy nestačí k určení závažnosti, pokud má uzel severity='warning'. Přesný test musí vycházet z kontraktu konkrétního požadavku.

Místní šablona, společná šablona a fallback

FN_SUBSIDIARY_SOAP_ERROR je v prozkoumaném engine.h definován: příslušné větve volají nejprve obsluhu konkrétní akce. Buildový soap-error.xsl se ale načítá jen pokud alespoň jeden substep má status="true". Samotná existence souboru nestačí (Soap::load:27696–27702).

Pokud místní šablona není dostupná, může se původní vstup předat společnému Soaps::Error. Pokud místní transformace nebo její výstupní převod selže, některé fallbacky však pokračují bez původního vstupu (Soap::Error:27339, 27345). Společná obsluha následně zkouší soap-unifault.xml nebo pevný fallback. XSL nemůže obnovit informace, které tato cesta již ztratila.

Odkud pochází ukázané „Something failed.“

Poštovní syncNew i syncChange při neúspěchu logují vrácený buffer přes událost 1021240. To odpovídá kontextu chyby „Při provádění akce nad synchronizovanou zprávou došlo k chybě“: pošta předává již vytvořený výsledek služby, místo aby sama doplnila transformační podrobnosti.

Ve zdrojovém serveru jsou dvě místa s doslovným Something failed.:

• SOAP větev convertOutputIn nenajde otevírací/uzavírací dvojici tagů v serializovaném výstupu.
• XML větev v prostoru http://www.flexideo.com/actions/xml totéž provádí pro prvního potomka obalu.

Obě předávají Detail=NULL, nastavují interní FN_SOAP_ERR_UNKNOWN a jako vstup chybové XSL dávají převáděný výstup. Prvním diagnostickým podkladem má proto být výstup posledního substepu před převodem.

Problematičtým kandidátem je platné XML <xm:root xmlns:xm="http://www.flexideo.com/actions/xml"><result/></xm:root>: textová extrakce hledá </result>, který samouzavírací zápis neobsahuje. To je slabina doložená čtením této větve, nikoli potvrzená příčina konkrétní uživatelovy chyby. Bez výstupního XML, akce, buildu a shody binárky se zdroji ji nelze určit.

Místní společná šablona má fyzický název soap-error.xsl, ale vkládá pevný text [by _tf/sp-error.xsl]. Značka proto nedokazuje použití souboru sp-error.xsl. Obecná větev používá Code, Reason, Detail; podrobnosti a kopii vstupu vkládá jen při naplněném detailu. Při NULL/nenastaveném Detail tak může ztratit i chybu, která ve vstupním XML existuje. Tento mechanismus byl reprodukován offline se syntetickou odpovědí v MSXML 6.

Jiné místní buildy importují http-error.xsl, která má vlastní protokolové větve. Jejich chování se nemá odvozovat z obecné SOAP šablony: rozhoduje skutečný importní řetězec buildu načteného z registru.

Jak informace zachovat pomocí transformací

Vodítko z přiloženého souborového logu

Dodatečně poskytnutý debug log z 14. 10. 2026 skutečně zachycuje jednotlivé vstupy, transformační výstupy a odpovědi serveru. V části před finálním výsledkem nebyly nalezeny markery type/status/severity="error" a poslední odpověď obsahuje save-result type="ok". To samo nepotvrzuje veškerou aplikační sémantiku, ale log neukazuje chybový SQL výsledek před uvedeným selháním.

Krok 4, substep 1 (temp-3-output.xsl) úspěšně vytvoří tento 193bajtový formátový výstup, který neobsahuje žádná poštovní data:

<http:root xmlns:asi="http://www.flexideo.com/actions/smtp-imap"
           xmlns:xm="http://www.flexideo.com/actions/xml"
           xmlns:http="http://www.flexideo.com/actions/http">
  <xm:root></xm:root>
</http:root>

Následuje Final result false a Fault Something failed. bez detailu. Tento konkrétní případ není samouzavírací potomek z předchozí hypotézy: xm:root nemá žádný vnitřní element. convertOutput odstraní HTTP obal; XML větev convertOutputIn pak přechází na firstChildElement() prázdného XML obalu a nenajde očekávaný element k vyříznutí. To přesně odpovídá větvi s obecným důvodem a NULL detailem v prozkoumaném zdrojovém kódu.

Bezprostřední problém je tedy prázdný výstupní XML obal posledního substepu. Následně dodaná finální XSL vysvětlila jeho vznik: vybírá /input/response[@type='ph-2-request']/save-result[@type='ok'], ale v logovém finálním vstupu byla odpověď ph-1-request/save-file. Vnější smyčka vytvoří xm:root, vnitřní nenajde žádný požadovaný výsledek. Novější dodané nastavení již předává odpověď ukládání přes 3-3 a tato XSL na správném syntetickém vstupu vytvoří operaci. Nastavení staršího logového buildu nebylo dodáno; původ tehdejšího nesouladu mezi nastavením, generováním a nasazením není určen. Pro návrat XML musí xm:root obsahovat skutečný výsledný element. Pokud má být odpověď záměrně prázdná, server má samostatný prostor http://www.flexideo.com/actions/empty; jeho použití závisí na kontraktu akce. Poštovní addOperations navíc z výsledku čte jednotlivé :operation a při absenci operací vrací úspěch; není ale náhradou za úspěšný předchozí převod výstupního formátu.

Tvar prázdného XML obalu je přidán do offline ověřovacího příkladu. Z přiloženého logu se do dokumentace nepřenášejí zprávy, osobní údaje ani jejich identifikátory.

Přímé obohacení chybové šablony

Řetězcový Detail a strukturované detaily

Další ověření dodané společné http-error.xsl ukázalo samostatnou chybu typů parametrů: obecná větev předává $Detail do makeDetail, nad nímž renderer provádí xsl:for-each. C++ ale Detail nastavuje jako řetězec BSTR, kdežto for-each v XSLT 1.0 vyžaduje množinu uzlů. Nenulový Detail tak může shodit samotnou chybovou transformaci. Bylo to reprodukováno v MSXML 6 se syntetickým parametrem obsahujícím jméno XSL.

Při úpravě rendereru zachovat Detail jako text a strukturované chyby vybírat samostatně ze vstupního dokumentu. Parametr pro uzly má mít výchozí prázdnou množinu, např. select="/..", nikoli text. Řetězec a uzly se nesmějí bez rozlišení iterovat stejnou instrukcí. Podporu SOAP, XML reprezentace JSON chyby, více chyb a zachování stop-only/termination lze ověřit odděleným adaptérem importujícím dosavadní společnou obsluhu.

Pro nativně detekovanou chybu odpovědi není vždy nutné vypínat kontrolu nebo měnit C++: chybová XSL již dostává odpověď. Obecná větev může vedle parametrů vybrat vstupní chybové uzly a zapsat jejich texty, kódy a názvy operací do detail. Stejný postup funguje nad <input><response>…</response></input>, pokud selhala navazující substepová transformace.

Výběr pouze /response/* nestačí pro odpověď pod /input/response. xsl:value-of nad množinou více chyb v XSLT 1.0 vrátí jen text první; pro více diagnostik použijte xsl:for-each nebo cílené kopírování.

Vlastní kontrola odpovědi

Pokud je nutná jiná interpretace výsledku nebo významová kontrola, nastavte na odesílajícím substepu avoid-response-check="true" a přidejte navazující substep s status="true". Jeho input from="x-y" odkazuje na odpověď odesílajícího substepu. Kontrola musí potřebné podrobnosti uchovat ve výstupu: při status="error" dostane chybová šablona nový výstup kontroly, nikoli automaticky celý původní vstup.

<action-step>
  <substep temp="query.xsl" send="true" avoid-response-check="true">
    <input from="0"/>
  </substep>
  <substep temp="check-response.xsl" status="true">
    <input from="1-1"/>
    <input from="content"><context action="example_action" step="1" substep="1"/></input>
  </substep>
  <substep temp="final.xsl">
    <input from="1-1"/>
    <input from="1-2"/>
  </substep>
</action-step>

Jde o fragment prvního transformačního kroku, nikoli úplný build. Vypnutí automatické kontroly musí doprovázet funkční následující kontrola. Kontrolní substep nesmí být poslední. Viz nativní kontrola a nastavení substepů.

Ověřitelný pracovní příklad

V dokumentačním repozitáři je adresář examples/service-error-details/:

Soubor	Účel
soap-error.xsl	Spojí parametry a vybrané chyby ze vstupu do SOAP Faultu; při chybě bez detailu uvede názvy kořene a přímých potomků XML.
check-response.xsl	Vrátí check-input se statusem a zachová odpověď pro chybovou obsluhu.
settings.fragment.xml	Ukazuje návaznost kontroly a samostatného finálního substepu.
verify.ps1	Offline zkoušky v MSXML 6 se syntetickými vstupy; volitelně reprodukce ztráty detailu původní šablonou.

powershell -NoProfile -ExecutionPolicy Bypass -File examples/service-error-details/verify.ps1

ExecutionPolicy platí pouze pro ověřovací proces v prostředí zakazujícím lokální skripty; nemění trvalou politiku. Příklady nevolají server. Ověřují parametry, více chyb, XML escaping, odpověď ve vstupu, návaznost kontroly, namespace, vnořený Fault, vynechání nesouvisejících dat a úspěch s varováním.

Příklady jsou diagnostický důkaz možnosti, nikoli úplná náhrada společné aplikační šablony. Pro nasazení zachovejte JSON varianty, HTTP metadata, stop-only, termination a známé validační větve. Obohaťte obecnou větev zdrojové XSL a regenerujte závislé buildy; generované buildové soubory neupravujte ručně jako trvalou opravu.

Chybové texty mohou obsahovat SQL, hodnoty vstupu nebo obsah zpráv. Konkrétní služba musí určit, které diagnostiky smí vracet. Kopírování celého poštovního nebo autentizačního vstupu do Faultu není nutné pro tento postup.

Rozpory a omezení

Téma	Dokumentovaný nebo očekávaný stav	Zjištění
Detail MSXML chyby	Popis nulté transformace uvádí hlášku SAXu.	getDetail() vrací jméno XSL nebo No template loaded.; getReason() obecné konstanty. HRESULT, řádek a podrobný parserový popis tato vrstva do parametrů nepřenáší.
Vazba procesoru na XSL	Transform má znát přidruženou šablonu.	Konstruktor s XSL inicializuje člen xslt=NULL a volá load(xslt), jehož tělo člen nenastavuje; operator= jej nastavuje. Jde o samostatnou nesrovnalost snapshotu, která zasahuje i použití xslt při transformaci. Vyžaduje revizi proti skutečně sestavené binárce.
Nativní detekce	Dokumentace popisuje obecný test chyb v odpovědi.	Testuje bool solveQuery nebo přesný řetězec type="error"; není úplným XPath testem všech protokolových chyb.
Statusová kontrola	Dokumentace ji popisuje na kmenovém uzlu.	Kód hledá status="error" nebo status='error' v bufferu; může reagovat i na takto zapsaný status potomka.
Dostupnost buildové chybové XSL	Soubor v buildu může působit jako automaticky používaný.	Načítá se při alespoň jednom status="true"; některé fallbacky ztrácejí vstup.
Převod platného XML	Strukturálně platné XML by mělo být zpracovatelné.	SOAP/XML extrakce textově očekává koncový tag; samouzavírací prvek je problematický kandidát.

Stávající řízení chyb navíc kombinuje namespace SOAP 1.1 se strukturou a názvy SOAP 1.2 a obrací význam Sender/Receiver. SOAP 1.1 používá faultcode, faultstring, faultactor, detail; SOAP 1.2 používá Code, Reason, Node, Role, Detail a jiný namespace. V SOAP 1.2 je Sender chyba odesílatele a Receiver chyba zpracování příjemcem. Zde popisujeme skutečné použití Flexideo; změna jeho kódů či SOAP verze není součástí rešerše. Podklady: W3C SOAP 1.1, Fault a W3C SOAP 1.2, Fault codes.

Diagnostika konkrétního běhu a otevřená práce

Pro samostatné nové selhání nejprve dohledat službu a build z registru a zachytit výstup před convertOutput, importy chybové XSL a statusové substepy. V dodatečně přiloženém logu již služba, build a prázdný finální XML obal vidět jsou. Následná rešerše dodané finální XSL potvrdila chybný typ odpovědi na jejím tehdejším vstupu; novější dodané nastavení používá správný odkaz. Pro potvrzení historického původu chyby by bylo potřeba původní nastavení z logového buildu.

Parser debug_actions podporuje ACTION, SOAP, LOGIN, CRON, NODES, MAIL a SINGLE. Pro poštu je relevantní MAIL; x-debug=true v URL funguje jen při povoleném jednotlivém debug volání. Soap::solve zapisuje do ../debug/ vedle buildu vstupy, výstupy, šablony, parametry, odpovědi i chybovou obsluhu. Rešerše debug nezapínala a obsah zpráv neshromažďovala. U ukládání voleb byl navíc zjištěn nesoulad ALLOW proti čtenému SINGLE; provozní nastavení musí respektovat skutečný parser příslušné verze.

Možné navazující změny serveru, dosud neimplementované:

• doplnit podrobné diagnostiky MSXML a původní HRESULT;
• opravit vazbu Transform::xslt a ověřit životní cyklus cache;
• zachovat původní XML ve fallbacku místní chybové transformace;
• ošetřit prázdné prvky nebo nahradit textové vyřezávání strukturálním převodem;
• přidávat jméno akce, build, krok a substep jako explicitní kontext;
• ověřit protokolové detektory, významové kontroly a všechny výstupní formáty.

Mapa důkazů pro pokračování

Serverový snapshot: commit 01112ea9144f10f99fb9c9d5832c3aae536fbc29; C++ při rešerši nebylo měněno. Základ cest je resources/source/Flexinet/Flexinet/.

Zdroj	Ověřené téma
engine.cpp:6932	Kompilace přes MSXML 6.
engine.cpp:16137–16192, 27209–27240	Procedura a kontrola registru.
engine.cpp:26826–27049; engine.h:1953–1975	Transformace, obecné důvody, detail a cache.
engine.cpp:27313	Chybové parametry, vstup a fallbacky.
engine.cpp:27427–27761, 27875–28166	Nastavení, substepy, vstupy a dispatcher.
engine.cpp:28313	Běh akce a chybové body.
engine.cpp:28848	Větve Something failed..
mail.cpp:2389–2490	Poštovní volání a logování výsledku.
core.h:679–685; core.cpp:1100–1112, 2226–2240, 3257–3270	Debug a nesoulad čtení/ukládání.
resources/source/vilibs/src/vilog_query.cpp:4–43	Čísla, závažnost a texty diagnostik v XML.

Markdownová rešerše zahrnula services/: nadřazené stránky, registr, nastavení, chyby, formáty a poštovní strukturu, dále požadavky action a do-action. Dotaz soap-error.xsl | avoid-response-check | action-steps znamenal OR mezi třemi skupinami. Dokumentační XML nebylo přepisováno ani použito k nahrazení Markdownu. Místní XSL GE-CRM byly čteny jako důkaz reprodukovatelného chování; nebyly měněny ani nasazovány.