Obsah trace v supportní akci

Supportní akce může převést XML COMEX.Trace na čitelný text pro další zpracování nebo pro popis požadavku v Jira Service Management. Transformaci provádí společná XSLT 1.0 šablona:

/shared/actions/temps/comex-trace-support-markdown.xsl

Šablona je součástí produktu intranetu. Formát vstupního XML vzniká v COMEXu; akce jej pouze převezme jako zdroj transformace. Nejde o obecný převod libovolného XML do Markdownu ani do Jira formátu.

Co akce zpracovává

Vstupem je kořenový uzel <trace>. Do výsledku se promítají jeho přímé stránky <page> a závěrečné lokální hodnoty <lsv>:

Uzel	Význam pro support
<trace>	Formát trace, jazyk, uživatel, zastupování a souhrnný počet stránek, serverových požadavků a LSV.
<page>	Jedna zaznamenaná obrazovka nebo rámec v pořadí, v němž se v trace objevil. Atribut url je hlavním identifikátorem stránky.
<event>	Událost životního cyklu stránky, například init, ready, redirect nebo reload.
<solve>	Jeden požadavek na server včetně času, výsledku, délky a kontextu vyvolání origin.
potomek <solve>	Vlastní název serverového requestu, například get-document, save-document, get-draft, save-draft nebo action.
<error>	Detail chyby serverové odpovědi; obvykle atributy detail, případně number a severity.
<param>	Parametr akce (name, value). Prázdná hodnota se ve výstupu výslovně označí.
<pdk-list-item>	Záznam, nad nímž akce pracovala: pdk, type a případně vtype.
<lsv>	Poslední známá Local Stored Value klienta; nejde o samostatnou událost.

Stránka, rámec a dynamický formulář

Stránka s win="frame" je v přehledu označena jako rámec nad stránkou. Je-li po takovém rámci nejbližší následující stránka win="window" se stejnou URL jako dříve otevřená stránka v okně, šablona ji označí jako návrat na stránku. Tím je z výstupu patrné otevření a následné zavření iframe formuláře.

Parametr id v URL identifikuje běžnou stránku. Hodnota id=dynamic znamená dynamický formulář; jeho kontext určují zejména parametry class, range, instance a key. Pro zobrazení dokumentu ve formuláři jde typicky o class=document, range=form, typ dokumentu v instance a primární klíč v key. Parametr referrer zachycuje zdrojovou komponentu.

Zapojení šablony do akce

1. Akce převezme úplný XML obsah trace, ne pouze jeden uzel page nebo solve.
2. Na kořen <trace> aplikuje společnou šablonu z /shared/actions/temps/.
3. V mechanismu parametrů XSLT nastaví podle cíle output-format; pokud jej nenastaví, použije se markdown.
4. Textový výsledek uloží jako hodnotu následujícího kroku akce, například do popisu supportního požadavku. Šablona má xsl:output method="text"; nevytváří XML, JSON ani Jira request.
5. Před odesláním zkontroluje citlivost URL, parametrů akcí a případných detailů chyb v konkrétním trace.

Akce musí předat skutečný XML uzel nebo dokument. Předání trace jako již XML escapovaného řetězce by transformaci znemožnilo; naopak po dokončení transformace je výsledkem obyčejný text.

Parametry šablony

Parametr	Výchozí hodnota	Význam
output-format	markdown	Volí výsledný formát: markdown nebo jira-wiki. Jiná hodnota transformaci úmyslně ukončí chybou, aby se omylem neodeslal nesprávný formát.
include-sensitive-values	no	Při no rediguje uživatele, zastupování, event/@extra, LSV a detail chyby. Hodnota yes je určena jen pro schválený interní tok.
documentation-base	https://docs.flexideo.cloud/supp-fxd-server-cz/requests	Základ URL pro odkazy na známé serverové requesty.
rendered-at	prázdné	Volitelný údaj o okamžiku sestavení výstupu. Při prázdné hodnotě se nevypíše.

URL stránek a hodnoty <action>/<param> jsou součástí supportního výstupu i při výchozí redakci. Prázdný parametr akce se nezaměňuje s redigovanou hodnotou: Markdown používá *(prázdné)*, Jira _prázdné_.

Výstup Markdown

output-format=markdown je výchozí a zachovává současný supportní formát. Každá stránka má číslovaný nadpis; hned pod ním je jako samostatný odstavec celá URL. Následují kontextové údaje, události, serverové požadavky, chyby, LSV a závěrečné shrnutí.

V rámci jednoho <solve> je nejprve uveden request a jeho vstupní atributy, parametry nebo PDK položky. Teprve za popisem vstupu následuje tabulka výsledku (status, doba a origin) a nakonec případná chyba odpovědi. Tento sled odpovídá diagnostickému čtení: co bylo požadováno → jak request skončil → jaká chyba přišla.

Známé requesty get-document, save-document, action, get-draft a save-draft získají přímo odkaz na svou serverovou dokumentaci. Neznámý request zůstane ve výstupu syrovým názvem bez zavádějícího odkazu nebo varování.

Výstup Jira wiki markup

Pro textové pole description v Jira Service Management nastaví akce output-format=jira-wiki. Výstup nepoužívá Markdown:

Obsah	Jira zápis
Hlavní a vnořené části	h1. až h5.
Popisné položky	* *Název:* hodnota
Technická hodnota	{{hodnota}}
Odkaz na stránku nebo request	`[popisek
Serverová chyba	{code:xml} … {code}

Výsledný Jira text neobsahuje Markdownové tabulky, backticky, **tučně**, odkazy ve tvaru [popisek](URL) ani code fences. Chybový uzel se vypisuje jako XML v code blocku; hodnoty atributů jsou pro čitelnost XML escapovány.

Jira větev zachovává stejné pořadí solve: nejprve request se vstupy, potom odrážky výsledku a nakonec code block případné chyby.

Sestavení Jira requestu

Transformace vytváří pouze text pro pole description. Obalující action sestavuje vlastní request a musí použít režim Jira wiki markup:

<isAdfRequest>false</isAdfRequest>
<description>…text vytvořený XSLT…</description>

Hodnota výsledku se do <description> vkládá jako textový uzel. XML serializer akce proto musí escapovat &, <, > a uvozovky podle kontextu. Do textu se nevkládá doslovné \n: šablona vytváří skutečné nové řádky pomocí 
.

Samostatné Jira custom field určené pro URL dostává pouze URL, nikoli zápis [popisek|URL]. Před vytvořením skutečného požadavku ověřte výsledný request přes POST /rest/servicedeskapi/request/validate.

Doporučené ověření akce

1. Transformujte reprezentativní trace bez parametru a ověřte, že jde o Markdown.
2. Transformujte stejný trace s output-format=jira-wiki a ověřte nadpisy, odrážky, odkazy a {code:xml} blok chyby.
3. Ověřte stránku win="frame", návrat do dřívějšího window, dynamický formulář s id=dynamic a alespoň jeden request action s parametrem i PDK položkou.
4. Ověřte prázdný parametr akce, URL s & a chybový detail; při výchozím nastavení nesmějí být citlivé hodnoty ve výsledku čitelné.
5. U Jira větve proveďte validační request před skutečným POST a zkontrolujte, že isAdfRequest je false.

Související témata

• Implementace intranetu
• Společné XSLT šablony akcí
• Akce v intranetu
• Serverový request action