Řešení problémů

Nejčastější chyby při nasazení a provozu a jak je diagnostikovat.

Ladicí režim a konzole

Ladicí režim vypisuje do konzole prohlížeče (F12, záložka Console), proč se pravidla chovají tak, jak se chovají. Neslouží jen návrhářům: správce z něj pozná, zda se skript spustil, zda pravidlo přeskočila neplatná pole a co změnilo pole na „neuložené“.

Zapnutí

Režim se vyhodnotí při otevření formuláře. Při vypnutí se nic nevypisuje ani nealokuje. Výpisy mají předponu [FC debug].

Co se loguje

• Průchod pravidel (sbalená skupina rules … s důvodem, režimem formuláře a počtem splněných pravidel). Uvnitř je pro každé pravidlo MATCH / no match s tabulkou podmínek (pole, operátor, očekávaná a skutečná hodnota, výsledek) a tabulkou provedených akcí. Přeskočená pravidla mají řádek SKIPPED s důvodem: vypnuté (disabled), neplatné (invalidReason), nesedící spouštěč (trigger) nebo žádné podmínky.
• Životní cyklus (lifecycle onLoad a onSave): změny polí, volané skripty, chyby blokující uložení.
• Vynucené hodnoty (forcedValue): změna pole z pravidla, případně BLOCKED by loop guard, když pravidla pole přepisují ve smyčce (ochrana po 10 aplikacích za sekundu).
• Skripty (script <zdroj> - ok / ERROR, doba běhu, výsledek, zprávy, chyba) a script skipped: tenant policy disabled při vypnuté politice skriptů.
• Výrazy: expression parse error (výraz se použil jako textová šablona) a expression non-finite result (dělení nulou nebo NaN, cílové pole se vymaže).
• Změny „dirty“ stavu (dirtyFields changed): tabulka polí, která se stala neuloženými, a zdroj změny (script:onFormLoad, rule:forcedValue, uživatel/widget…). Hodí se k odhalení formuláře, který hlásí neuložené změny hned po otevření.

Čítač renderů

V ladicím režimu je k dispozici objekt window.__fcRenderCounts: počet vykreslení jednotlivých komponent (podle názvu pole). Zadejte ho do konzole a sledujte, zda jedno pole nepřekresluje celý formulář. Při normálním provozu nic nezabírá.

// po zapnutí režimu a otevření formuláře
console.table(window.__fcRenderCounts)

Formulář se nezobrazí

1. Je formulář aktivní? Spusťte Manage-FormCustomizer.ps1 -Action Status nebo otevřete dialog „Vlastní formulář“ (pokud je formulář již aktivní, tlačítko na liště nese název „Otevřít editor FormCraft 365“ a stav aktivace najdete v návrháři pod „Aktivace na seznamech“). Viz Aktivace. Stav „JINÁ KOMPONENTA“ znamená, že seznam používá jiný formulář.
2. Je balíček nasazený a povolený? V App Catalogu zkontrolujte, že je sloupec „Enabled“ a „Deployed“ nastavený a že u tenantového nasazení byla zvolena volba pro všechny weby.
3. Aktualizace se neprojevila: po nahrání nové verze obnovte stránku s vyprázdněním cache (Ctrl+F5). Nová verze musí mít vyšší číslo (viz Aktualizace).
4. Formulář se otevře s výchozím rozložením: konfigurace se nenačetla. Viz Stavy načtení konfigurace.
5. Otevřete konzoli a hledejte chybu s předponou [CustomFormCustomizer] nebo hlášku „Chyba při inicializaci formuláře“.

Stavy načtení konfigurace

Při otevření formuláře se konfigurace čte ze souborů config.json a backup.json seznamu a vyhodnotí se jedním ze čtyř stavů.

Stav ok může mít i příznak „novější verze“, viz níže.

Neplatná konfigurace a panel Raw JSON

Je-li uložená konfigurace neplatná, nikdy se tiše nepřepíše výchozím stavem. Správce formuláře dostane upozornění a tlačítko Opravit konfiguraci, které otevře návrháře s panelem Uložená konfigurace je neplatná.

1. V panelu si přečtěte Nalezené problémy (cesta a důvod podle schématu, nebo chyba syntaxe JSON).
2. Upravte JSON v poli Uložená konfigurace (Raw JSON). Typicky doplníte chybějící povinnou vlastnost nebo opravíte překlep v názvu typu pole.
3. Klikněte na Ověřit a použít JSON. Platná konfigurace se načte do návrháře a odemkne se ukládání.
4. Změny uložte běžným tlačítkem uložení.

Historie konfigurace

Před každým přepsáním se dosavadní konfigurace zkopíruje do složky SiteAssets/FormCustomizer/<listId>/history/ jako soubor <listId>.<časová značka>.json. Uchovává se posledních 10 verzí. Zápis historie má časový limit 5 sekund a jeho selhání uložení neblokuje. Při prvním zamčení úložiště se historie z doby před zámkem smaže (nedůvěryhodný obsah).

Návrhář zatím nemá tlačítko pro obnovu z historie. Postup:

1. Otevřete knihovnu Site Assets, složku FormCustomizer/<listId>/history (ID seznamu zjistíte v adrese nastavení seznamu nebo příkazem Get-PnPList).
2. Stáhněte požadovanou verzi a otevřete ji v textovém editoru.
3. V návrháři otevřete panel Raw JSON, vložte obsah a klikněte na Použít JSON, nebo použijte import konfigurace.
4. Uložte formulář.

Poslední záloha (jedna verze) je navíc dostupná v menu návrháře jako Obnovit ze zálohy.

Konfigurace z novější verze produktu

Každá uložená konfigurace nese schemaVersion. Pokud je vyšší než verze, kterou balíček podporuje (například jste nahráli starší .sppkg), formulář se zobrazí „podle nejlepší možnosti“, ale ukládání je zablokováno, aby nedošlo ke ztrátě dat. Návrhář ukáže „Konfigurace pochází z novější verze produktu“ s verzemi schématu. Řešení: aktualizujte balíček na novější verzi (viz Aktualizace). Konfiguraci starší verzí nepřepisujte.

Konfigurace se neukládá nebo se ztrácí

HTTP 403 při ukládání

Hláška „Nemáte oprávnění k provedení této operace v SharePointu (HTTP 403)“ znamená, že uživatel nemá zápis do složky konfigurace. Nejčastější příčiny:

• Úložiště je zamčené a uživatel není vlastník webu ani člen skupiny návrhářů (a podsložka seznamu pro ni existuje). Přidejte ho do skupiny návrhářů a nechte vlastníka formulář znovu uložit (viz Skupina návrhářů).
• Návrhář ukládá do seznamu, jehož složku ještě nikdo nezaložil: „Složka konfigurace tohoto seznamu ještě neexistuje. Vlastník webu musí formulář nejdřív uložit.“
• Ukládáte licenci do zamčené složky jako člen: „Licenci do zamčené složky FormCustomizer mohou uložit jen vlastníci webu.“
• Uložení do tenantové Storage Entity (licence, politika skriptů) vyžaduje správce tenantového App Catalogu.

Úložiště není zamčené

Varování „Úložiště konfigurace není zamčené: kdokoli s oprávněním Správa seznamů ji může přepsat“ se zobrazuje vlastníkovi po uložení, pokud se zámek nepodařil nebo ho nikdo nenastavil. Řešení: uložte formulář (nebo klikněte na Zamknout nyní) jako vlastník webu s oprávněním Správa oprávnění, případně spusťte příkaz z PowerShellu. Varianty hlášek:

• Zamčení úložiště selhalo (…): zkuste to znovu jako vlastník nebo spusťte PowerShell.
• Návrat původních oprávnění se nepodařil: složka může mít omezený přístup, spusťte opravu v PowerShellu.
• Čtení se nepodařilo nastavit pro: …: zámek je platný, ale princip pro organizaci nebo hosty se nepodařilo vyřešit (např. omezení tenantu). Vypněte příslušný přepínač.
• Skupina návrhářů … neexistuje / je skupina Členové nebo Návštěvníci / obsahuje Everyone: opravte název skupiny (viz Odmítnuté skupiny).

Chyba HTTP 400 u cest k souborům

Hláška „Specified value is not supported for the serverRelativePath parameter“ (HTTP 400) znamená, že se do SharePointu poslala cesta relativní k webu. Funkce pro soubory a složky vyžadují cestu od kořene serveru (/sites/<site>/SiteAssets/…). V produktu se cesty skládají správně. Narazíte na to hlavně u vlastních skriptů, dotazů nebo ručních úprav kódu: použijte toServerRelativePath.

Konflikt uložení (412)

Při uložení položky se kontroluje ETag: pokud ji mezitím upravil jiný uživatel, SharePoint vrátí HTTP 412 a formulář zobrazí dialog Položka byla změněna jinde s informací, kdo a kdy ji změnil. Uživatel zvolí:

• Načíst znovu: zahodí své změny a načte aktuální verzi,
• Přesto přepsat: uloží své hodnoty přes cizí změny,
• Zrušit: vrátí se do formuláře.

Není to chyba nasazení. Pokud konfliktů vidíte neobvykle mnoho, hledejte workflow nebo automatizaci, která položku mění krátce po otevření formuláře. Hláška „Položka byla mezitím upravena jiným uživatelem. Obnovte prosím stránku (HTTP 412)“ se objeví u operací, které dialog nenabízejí. Chování popisuje Práce s formulářem. Konfigurace formuláře konflikt 412 nehlásí (ukládá se podle savedAt, ne podle ETagu).

Nenačtená pole

Hodnoty položky se načítají po dávkách ($select / $expand). Pokud některá dávka selže (oprávnění ke zdrojovému seznamu, chyba SharePointu), formulář se přesto otevře a pole z neúspěšné dávky zobrazí jako jen pro čtení s pruhem „Pole se nepodařilo načíst a jsou jen ke čtení (neuloží se): …“. Při uložení se nezapíší, takže nedojde k přepsání dat prázdnou hodnotou. Řešení: formulář načtěte znovu, ověřte uživateli čtení zdrojových seznamů (lookup, taxonomie, uživatelé).

Neindexovaný sloupec

U seznamů s více než 5 000 položkami SharePoint odmítne dotaz filtrující neindexovaný sloupec (limit zobrazení seznamu). Widgety Související položky a Související dokumenty proto takový dotaz nespustí a ukážou „Sloupec „…“ není indexovaný. U seznamů s více než 5 000 položkami musí být indexovaný.“ Řešení:

• Ve zdrojovém seznamu nastavte index na sloupci cizího klíče (Nastavení seznamu, Indexované sloupce), nebo
• v návrháři ve zdroji widgetu klikněte na Zaindexovat sloupec (vyžaduje oprávnění ke správě seznamu).

Vyhledávání v lookup polích nad 500 položek se automaticky přepne na dotaz po zadání alespoň dvou znaků (zobrazí se nápověda „Začněte psát pro vyhledání…“), takže se tam indexace řešit nemusí.

Skripty nefungují

1. Jsou skripty povolené? Výchozí stav je vypnuto. Správci formuláře uvidí pruh „Vlastní skripty jsou na tomto tenantu vypnuté…“. Povolení viz Politika skriptů. Změna se projeví do 15 minut.
2. V ladicím režimu hledejte script skipped: tenant policy disabled (politika) nebo script … ERROR (chyba v kódu).
3. Hláška o CSP / unsafe-eval znamená, že prostředí dynamické spouštění zakazuje, viz CSP.
4. Při vypnutých skriptech se neprovádí onBeforeSave a uložení se neblokuje. Použijte pravidla s akcí blockSave.

Licence nebyla rozpoznána

Návrhář zobrazuje Community Free, přestože máte klíč:

1. Otevřete dialog Licence a vložte klíč znovu. Dialog ho ověří a řekne důvod (jiný tenant, jiná site collection, vypršel, neplatný podpis…). Tabulka hlášek je v Licence.
2. Ověřte, že je klíč uložený tam, kde se čte: tenantová Storage Entity, nebo SiteAssets/FormCustomizer/license.txt v kořenovém webu site collection.
3. Změna provedená mimo návrhář (PowerShell, ruční soubor) se může projevit až za hodinu (cache surového klíče). Okamžitě po vymazání klíčů _fc_lic_* v localStorage.
4. Klíč pro vybrané site collection neplatí v ostatních. Pošlete dodavateli ID site collection z dialogu.

Na liště seznamu chybí tlačítko „Vlastní formulář“

Postupujte od prvního kroku. Nejčastější příčiny odhalí první kroky:

1. Podívejte se do menu … na pravém konci příkazové lišty. Pokud je lišta přeplněná, SharePoint vlastní příkazy přesune právě sem. Rozšíření to ovlivnit nemůže.
2. Synchronizace Microsoft Lists. Příznak: první načtení po „Clear site data“ tlačítko zobrazí, další obnovení (F5) už ne; jiné seznamy, které synchronizace nezpracovává, fungují. Příčinou je místní synchronizační klient OneDrivu (Microsoft Nucleus), který při obsluze stránky přes service worker vrací data seznamu lokálně. Jeho odpověď má "ShouldLoadSPFramework": false a vlastní akce bez rozšíření SPFx, takže SharePoint balíček rozšíření jen předběžně načte („preloaded but not used“) a onInit příkazové sady se nikdy nezavolá. Naším kódem to ovlivnit nelze, SPFx se vůbec nespustí. Zjištění: F12, karta Network, požadavek RenderListDataAsStream míří na localhost:42050 (případně má hlavičku server: MicrosoftNucleus). Doporučené trvalé řešení: v nastavení seznamu (Upřesnit nastavení, Dostupnost offline klienta) zvolte Ne, nebo při aktivaci formuláře ponechte zaškrtnutou volbu Vypnout offline dostupnost seznamu (nastaví vlastnost seznamu ExcludeFromOfflineClient; seznam pak nebude dostupný offline). Návrhář na to upozorní v záložce Akce seznamu. Alternativa na úrovni tenantu nebo zařízení: zásada DisableListSync. Další možnosti: seznam otevřít způsobem, který synchronizace Lists neobsluhuje, případně dočasně vyčistit data webu; trvale může tenant nebo uživatel synchronizaci Microsoft Lists vypnout (možnosti zjistěte v dokumentaci Microsoftu; parametr Set-SPOTenant -DisableListSync ověřte v dokumentaci Microsoftu).
3. V seznamu Tenant Wide Extensions nesmí mít žádný záznam komponent Form Customizeru Disabled = Yes. Zakázaný záznam SharePoint vůbec nedoručí, takže příslušný příkaz (např. FormActivatorCommandSet-100 pro lištu) se nespustí.
4. Tlačítko vidí jen uživatelé s oprávněním ManageWeb na seznamu (vlastníci webu, plný přístup). Výsledek kontroly se ukládá do sessionStorage pro každou kartu zvlášť, proto seznam otevřete v nové kartě, případně po změně oprávnění.
5. Zkuste seznam otevřít v anonymním okně. Pokud se tam tlačítko zobrazí, drží běžné okno zastaralá data webu (typicky po opravě záznamů Tenant Wide Extensions): F12, karta Application, Storage, Clear site data, poté Ctrl+F5.
6. Příkaz je dostupný na seznamech se šablonou 100, 120 a 1100. Knihovny dokumentů (šablona 101) příkaz nemají.
7. V App Catalogu zkontrolujte seznam Tenant Wide Extensions. Musí obsahovat 6 záznamů pro šablony 100, 120 a 1100: 3 záznamy lišty s Component Id 4a8b7c12-5d3e-4f9a-8b1c-6e2d9f4a3b5c a 3 záznamy kontextového menu s Component Id a9998067-8e06-423f-b8a0-3177988f3a42 (od verze 1.28.1). Staré záznamy kontextového menu (FormActivatorCommandSet-ContextMenu-*) smažte, vytvářejí duplicitní registrace. Chybějící doplňte a zastaralé smažte, postup je v instalaci.
8. Ověřte, že se balíček načetl. V konzoli prohlížeče (F12) spusťte performance.getEntriesByType("resource").some(e => e.name.includes("form-activator")). Hodnota true znamená, že se rozšíření načetlo. Po navigaci mezi seznamy v aplikaci může hodnota patřit předchozímu seznamu, proto kontrolujte v nové kartě s otevřeným seznamem.
9. Změny se na webech projeví zhruba do 20 minut. Poté obnovte stránku klávesami Ctrl+F5.
10. Zapněte diagnostiku rozšíření. V konzoli prohlížeče (F12) na stránce seznamu spusťte localStorage.setItem("fc.debug","1") a obnovte stránku. Výpis se objeví jako varování konzole (console.warn) s předponou [FormCraft]. SharePoint během načítání konzoli maže, proto v nastavení konzole DevTools zapněte Preserve log. Řádky začínající [FormCraft] uvádějí, která komponenta běží (FormActivatorCommandSet = lišta, FormListActionsContextMenu = kontextové menu), její vlastnosti registrace, ID a šablonu seznamu, vstupy kontroly oprávnění a výslednou viditelnost hlavního příkazu, počet načtených akcí seznamu, rozhodnutí o viditelnosti jednotlivých slotů a každé překreslení lišty. Pokud není vidět žádný řádek [FormCraft], komponenta se nespustila (viz synchronizace Microsoft Lists a kontrola registrací výše). Diagnostiku vypnete příkazem localStorage.removeItem("fc.debug").

Šum v konzoli

Některé zprávy v konzoli nejsou chyba:

• Požadavky s HTTP 404 na config.json, backup.json, license.txt, history nebo na Storage Entity: soubor ještě neexistuje (formulář ještě nikdo neuložil, klíč není nastaven). Je to očekávané a funkčnost to neovlivní.
• [ConfigService] … varování: pomocné operace, které mohou selhat bez dopadu na uložení (kopie do historie, úklid historie, ověření členů skupiny návrhářů).
• Hlášky z vlastního kódu SharePointu a ostatních částí stránky (SPFx host, webparty, telemetrie) nesouvisejí s tímto produktem.

Skutečný problém poznáte podle hlášky v rozhraní (červený nebo žlutý pruh) nebo podle chyby s předponou [CustomFormCustomizer], [FormActivatorCommandSet] či [FC debug] (jen v ladicím režimu).

Co poslat podpoře

Připravte tyto údaje (bez osobních dat):

1. Verzi balíčku (solution.version z App Catalogu) a verzi dokumentace.
2. URL webu a ID seznamu, režim formuláře (nový, úprava, zobrazení) a kroky k reprodukci.
3. Výstup Manage-FormCustomizer.ps1 -Action Status.
4. Konzoli prohlížeče z načtení se zapnutým ?fcdebug=1 (uložit jako text; ověřte, že neobsahuje data z formuláře).
5. Záložku Network s neúspěšnými požadavky (stav, URL, text odpovědi).
6. Konfiguraci formuláře: export z návrháře (tlačítko Exportovat), případně config.json ze složky seznamu.
7. Stav úložiště konfigurace (zamčeno, nezamčeno, skupina návrhářů) a zda je zapnutá politika skriptů.
8. U licence: ID tenantu a ID site collection z dialogu a přesnou hlášku (klíč samotný nezasílejte nezabezpečeným kanálem).