Repository Query

🇨🇿  česky    🇬🇧  english

Pokročilou funkcí, která umí pracovat s externími daty je Repository. Jedná se o možnost zobrazovat ve virtuálním asistentovi (VA) data uložená zpravidla v Google sheet, pracovat s nimi a jednoduše je aktualizovat v tabulce.

Správné fungování Repository vyžaduje 3 kroky:

  1. Vytvoření Google sheetu a jeho nasdílení
  2. Napojení VA na vytvořený Google sheet
  3. Využití dat ve VA

K prvotnímu napojení repository s Vaším botem je potřeba součinnost s Feedyou

Vhodným doplněním integračního kroku Repository je také ošetření případů, kdy integrace nevrátí žádná data, a to pomocí kroku Switch.


 

Vytvoření tabulky

Nejdříve je nutné si na Google disku vytvořit a správně nastavit Google sheet, ze kterého si má VA sbírat data. Nejdůležitější je nastavení sdílení, které musí být umožněno "všem, kteří mají odkaz" a tito musí mít oprávnění na úrovni "Editor". Toto nastavení je pod tlačítkem "Sdílet" v pravém horním rohu stránky.

image-1642359435983.png

Ve spodní části dialogového okna dále zvolit možnost "Změnit" a vybrat možnost "Všichni uživatelé, kteří mají odkaz".

image-1642359473842.png

image-1642359512687.png

V rolovacím menu napravo je ještě třeba upravit práva - tedy to, na jaké úrovni může uživatel konkrétní dokument upravovat, na možnost "Editor".

image-1642359546356.png

 

Nastavení Google sheet je takto hotové a tabulka je připravena pro napojení do virtuálního asistenta.

 

Napojení tabulky

V nastavení celého virtuálního asistenta - Bot settings je třeba nastavit kategorii Repository, která je součástí oddílu Integrations. Na tomto místě je možné připojit do virtálního asistenta libovolné množství zdrojů dat, více listů jednoho dokumentu nebo i více tabulek.

V kategorii Repository je nutné určit zdroj dat - Data sources, toto nastavení určuje virtuálnímu asistentovi, odkud má data čerpat. 

Parametry
  • Data sources/typ datového zdroje - Slouží k rozpoznání zdroje dat (momentálně podporuje pouze typ Google sheet)
  • Source ID - Slouží jako klíč k následnému filtrování dat z daného zdroje. Je třeba si ID zvolit, a to ideálně tak, aby korespondovalo s obsahem. Např. pokud se jedná o výrobky, je možné zvolit jako Source ID "products" atp.
  • Spreadsheet url - Odkaz na zdrojovou tabulku (bez /edit#gid=0 na konci odkazu)
  • Sheet name - Název listu v tabulce (pokud je v tabulce více listů, ze kterých je žádoucí čerpat data, musí být pro každý tento list samostatný Data source.

image-1643627104629.png

Formát tabulky

Ke správnému rozeznání dat v tabulce je třeba dodržet správný formát:

  1. První je sloupec "name" - název dané položky
  2. Další sloupec je "id" - unikátní id dané položky - id musí být ve formátu bez diakritiky a mezer (např. "zubni-pasta")
  3. Další sloupce mají vždy prefix "tag" - mohou sloužit k filtrování dat podle různých kategorií - těchto sloupců může být libovolný počet, ale nemusí být také žádný, i v těchto sloupcích je nutný formát bez diakritiky a mezer
  4. Následující sloupce už jsou libovolné (např. popis výrobku, cena, odkaz na e-shop, obrázek - ten musí být nahrán ve VA v Media gallery a do tabulky následně zkopírován odkaz vygenerovaný odsud)

Tabulku je následně třeba naplnit daty, která se mají ve struktuře objevovat. Například tedy seznamem produktů nebo jinými položkami. 

Příklad jak může vypadat tabulka připravená pro použití je zde.

 

Použití dat

Nyní jsou připraveny všechny podklady a nastavení pro využití dat z tabulky ve virtuálním asistentovi. Aby mohl VA správně použít data, je nutné uložit je do storage. K tomu je třeba využít integrační krok:

Nastavení integrace

Krok Integration a typ Repository Query

image-1642365066077.png

Po vložení integračního kroku do struktury je nutné ho nastavit. V rolovacím menu je nutné zvolit typ Repository Query a vybrat zdroj dat Source - jedná se o Source ID zvolené při nastavovaní Repository na úrovni celého virtuálního asistenta (např. "products").

image-1642365367863.png

Nyní je daná storage naplněná všemi daty z tabulky, což může být někdy žádoucí, ale často je potřeba ještě data vyfiltrovat podle kategorií. K tomu slouží sekce "Tags".

image-1642365632727.png

Tagy umožňují vyfiltrovat pouze část dat spadající do některé z definovaných kategorií. Lze vyfiltrovat všechny položky s určitým příznakem, například "potraviny". Tag je třeba sestavit následujícím způsobem: tag (bude vždy součástí výrazu), dále název sloupce, ve kterém se příznak nachází a na závěř název příznaku. Tagů lze nastavit libovolné množství.

Výsledný výraz bude pak mít tuto podobu: tag-kategorie-příznak.

 

Zobrazení dat

Data vybraná z tabulky lze zobrazit a využít kdekoli ve struktuře, jedním z nejvhodnějších zobrazení je využití dat v carouselu.

Pro zobrazení dat v carouselu je třeba si nejprve vytvořit krok, ve kterém se mají data zobrazovat. Může se jednat o krok typu Closed question s odpověďmi na carouselu, krok typu Message s carouselem nebo lze proměnné rovnou zobrazovat i v textu zprávy. Pro příklad je využita možnost s využitím Closed question. Po vytvoření je třeba zvolit odpověď k otázce ve formátu carousel. Její nastavení (popsáno níže) lze následně použít jako šablonu pro zobrazení každé jedné položky, kterou integrace vrátí. Je třeba nastavit i tuto konkrétní odpověď - settings buttonu.

image-1643628009336.png

Screenshot 2022-03-03 at 10.45.49.png

Question krok musí být vložen až za integrační krok

V nastavení carouselu je třeba vyplnit příslušnou storage, ze které se budou čerpat data = položky. Toto nastavení je ve formuláři na konci - Template. Jedná se o defaultně pojmenovanou storage, která bude vypadat takto: repository-query-items. Je důležité ji vyplnit přesně, aby se data čerpala správně.

image-1643628225237.png

Nyní bude při zobrazování carouselu krok vytvářet kartu carouselu pro každou položku.

Dále je třeba v nastavení carouselu vyplnit formulář v úvodu - viz níže. Tento formulář určuje, jaké položky tabulky se budou v carouselu zobrazovat - např. Title - název, Subtitle - krátké doplňující info, podtitulek, Text - popis položky, Image - obrázek, který musí být v tabulce uložen ve formátu URL vygenerované z Media gallery v Designeru, Button - tlačítko, případně i Condition - zapodmínkování. Toto nastavení bude platné pro všechny položky, které se díky integračnímu kroku nahrají do struktury. Pole musí být vyplněna vždy ve tvaru template.nazev sloupce - proměnná template zajistí, že nastavení bude platné pro všechny položky, následuje tečka a název sloupce tak, jak je uvedený ve zdrojové tabulce.

Pokud je žádoucí pro každou položku zobrazit její název, popisek, cenu a obrázek, je třeba vyplnit nastavení šablony například takto:

image-1643628400113.png

carousel repository.png

V praxi se pak za každou proměnnou ({template.name}, {template.Popisek} atp.) bude dosazovat příslušný text podle tabulky (např. "Jablka", "Čerstvé, šťavnaté ovoce oblíbené především v Evropě a Severní Americe..")

 

Takto je nastavení samotného Repository hotové, může se ale také stát, že integrace nevrátí z tabulky do VA žádná data, protože např. žádná z položek neodpovídá zadanému filtrování, a je třeba podchytit i tuto možnost. Pro takový případ se do struktury vkládá krok typu Switch, který je nastaven tak, aby VA dokázal na situaci zareagovat. Tento switch je vhodné umístit ve struktuře před carousel, ve kterém se mají zobrazovat položky.

 

Nastavení switche

Switch na rozdělení zda repository-query nalezl nějaké položky je třeba nastavit takto:

Title/název - co switch vyhodnocuje, např. "Vrátila tabulka položky?"

Expression/výraz - storage, podle které se má switch vyhodnocovat, v tomto případě to bude vždy {repository-query-count}, tato storage obsahuje počet položek, které integrační krok našel a vrátil. Na základě tohoto počtu se switch bude rozhodovat:

1. větev switche (ne default): 

Title/název - z tabulky se nevrátily žádné položky, např. "Ne", "Nevrátila"

Value/hodnota - určuje, kolik položek se musí z integrace vrátit, aby bylo žádoucí odeslat uživatele touto větví. Většinou půjde o případ, kdy se nevrátí žádná položka a tedy se bude value = 0. Nevrátila-li se tedy žádná položka, bude na místě v této větvi nastavit zprávu o chybě, např.: "Omlouváme se, ale nenašli jsme žádný vhodný produkt." a následně nastavit větev dle preferencí.

2. větev switche (default): 

Defaultní větev nevyžaduje žádné nastavení, touto možností projde uživatel vždy, když bude mít Repository požadovaný výsledek a bude tedy možné zobrazit položky.

 

Aktualizace zdrojové tabulky

Se realizuje pomocí speciální URL adresy s kódem, kterou zajistí na vyžádání account manager.

 

Přepnutí na produkční/testovací verzi bota

Pozor! Při přepnutí na produkční verzi bota je momentálně potřeba kooperace s account managerem.

Při přepnutí bota z testovací instance na produkční (nebo opačně při zakládání testovací instance z produkční), u které ještě nebylo nastaveno Repository, je potřeba upozornit account managera, který Vám zašle nový odkaz na update Repository tabulky (liší se od testovací instance) a zajistí založení Repository (tabulka se nezakládá automaticky).

Na automazici těchto procesů momentálně pracujeme, aby přechod na produkční/testovací verzi byl plynulý a dokázali jste celý proces obsloužit z Feedyou Designer.