OData konektor (Power BI)

Hlavní nabídka Nastavení Obecné Ostatní OData konektor (Power BI)

OData konektor (Power BI)

OData konektor umožňuje reportingovým nástrojům, jako je Power BI, číst vytěžená data přes OData. Data Vaší společnosti jsou k dispozici jako OData feed (OData v4), který můžete načíst do Power BI a nad ním sestavovat vlastní reporty a přehledy.

Ve feedu jsou k dispozici:

doklady (jedna tabulka pro každý typ dokumentu)
položky dokladů
uživatelé
účetní jednotky

Feed je pouze pro čtení – data přes něj nelze měnit.

Feed obsahuje doklady všech účetních jednotek

Feed vždy obsahuje doklady všech účetních jednotek Vaší společnosti. Nastavení Účetní jednotka a Další účetní jednotky u klientské aplikace se na data ve feedu neuplatní.

Aktivace funkce

OData konektor je placená funkce. Zapíná ji Alice (obchodní oddělení nebo podpora) – sami ji v aplikaci zapnout nemůžete.

Stav funkce zjistíte v Nastavení → Obecné → Ostatní u položky OData konektor (Power BI). Přepínač u této položky nelze změnit, slouží pouze k zobrazení stavu.

Stav funkce	Přepínač	Zobrazený text
Neaktivní	vypnutý	Pro aktivaci této funkcionality kontaktujte naše obchodní oddělení.
Aktivní	zapnutý	Umožňuje reportingovým nástrojům, jako je Power BI, číst vytěžená data přes OData.

Data po zapnutí funkce

Po zapnutí funkce jsou data ve feedu dostupná až po prvním obnovení. Více v sekci Aktualizace dat.

Co budete potřebovat

Aktivní funkci OData konektor (Power BI)
Klientskou aplikaci s vhodnou rolí a její přihlašovací údaje (ID klienta a Heslo)
Power BI

Klientská aplikace pro Power BI

Power BI se k feedu přihlašuje pomocí přihlašovacích údajů klientské aplikace. Postup vytvoření klientské aplikace naleznete v sekci Vytvoření klientské aplikace. Klientské aplikace spravuje pouze Administrátor.

Pro napojení Power BI je specifické následující:

Role klientské aplikace

Role klientské aplikace musí mít oprávnění vidět všechny dokumenty.

Role	Vhodná pro Power BI
Zpracovatel	Ano
Schvalovatel	Ano
Administrátor	Ano
Vlastní role s oprávněním vidět všechny dokumenty	Ano
Nahrávač	Ne
Zpracovatel účetní jednotky	Ne
Schvalovatel účetní jednotky	Ne

Pokud role klientské aplikace nevyhovuje, feed vrátí chybu 403 s hláškou The client application must have the ViewAllDocuments permission.

Uložení hesla

Po uložení klientské aplikace se zobrazí dialog Klientská aplikace úspěšně vytvořena s údaji ID klienta a Heslo. Obě hodnoty si zkopírujte ikonou Zkopírovat do schránky a pečlivě uložte – budete je zadávat v Power BI.

Heslo se zobrazí pouze jednou

Pečlivě si uložte zobrazené údaje, po zavření dialogu již nebude možné klientské heslo zobrazit.

Pokud heslo ztratíte, klientskou aplikaci smažte, vytvořte novou a v Power BI změňte přihlašovací údaje na nové.

Napojení v Power BI

V Power BI zvolte načtení dat z OData feedu (OData v4).
Jako URL zadejte:
```
https://api.redque.com/v1/odata
```
Jako způsob ověření zvolte Základní (Basic) a vyplňte:
- Uživatelské jméno: ID klienta klientské aplikace
- Heslo: Heslo klientské aplikace
Vyberte tabulky, které chcete načíst.
V Power BI vytvořte vztahy mezi tabulkami – viz Vztahy mezi tabulkami.

Přihlašovací údaje uživatele nefungují

Pro přihlášení použijte vždy ID klienta a Heslo klientské aplikace. Váš přihlašovací e-mail a heslo do Alice pro přihlášení k feedu nefungují.

Feed nabízí tyto adresy:

URL	Obsah
`https://api.redque.com/v1/odata`	Seznam tabulek – tuto URL zadejte do Power BI
`https://api.redque.com/v1/odata/$metadata`	Popis tabulek a sloupců (XML)
`https://api.redque.com/v1/odata/<NázevTabulky>`	Data konkrétní tabulky

Aktualizace dat

Data ve feedu jsou kopií dat z Alice, která se obnovuje jednou denně.

Změny provedené v Alice se ve feedu projeví až po dalším obnovení.
Po zapnutí funkce jsou data dostupná až po prvním obnovení. Do té doby feed vrací chybu 404 s hláškou The data of the tenant has not been prepared yet.

Které doklady feed obsahuje

Feed obsahuje data celé společnosti. Ve feedu jsou všechny doklady kromě:

dokladů, které se právě nahrávají
dokladů bez určeného typu
smazaných dokladů (v koši)

Tabulky typů dokumentů, které byly deaktivovány, ve feedu zůstávají.

Dostupné tabulky

UsersAccountingUnitsTyp dokumentuPoložky dokladů

Uživatelé společnosti.

Sloupec	Poznámka
UserId
FirstName
LastName
FullName
Email	U klientské aplikace obsahuje ID klienta
IsActive
IsClientApplication	`true` u technických účtů klientských aplikací
UserRoleId
AccountingUnitId

Tabulka obsahuje i technické účty klientských aplikací (IsClientApplication = true).

Účetní jednotky.

Sloupec	Poznámka
AccountingUnitId
Name
CustomerId	IČO
CustomerVatId	DIČ
ExternalId
IsVatPayer
IsSingleEntryAccounting

Pro každý typ dokumentu (např. faktury CZ, účtenky…) je ve feedu jedna tabulka. Názvy tabulek odpovídají interním názvům typů dokumentů a liší se podle nastavení Vaší společnosti.

Sloupec	Poznámka
DocumentId
AccountingUnitId
OwnerId
ValidatorId
CurrentApproverId
LastApproverId
State
FileName
Source
Created
ValidationTime
ExportedTime
DeliveredDate
IsPaid
DatePaid
Tags	Text ve formátu JSON

Dále tabulka obsahuje všechna pole typu dokumentu včetně vlastních polí. Název sloupce odpovídá internímu názvu pole. Pokud se název pole shoduje s některým z pevných sloupců výše, dostane sloupec příponu _Field.

Položky dokladů jsou v tabulce <název typu dokumentu>_Items. Tabulka existuje jen u typů dokumentů s položkami.

Sloupec	Poznámka
DocumentId
ItemIndex	Pořadí položky na dokladu (číslováno od 0)
AccountingUnitId
State
Created

Dále tabulka obsahuje všechna pole položek daného typu dokumentu.

Datové typy

Hodnota v Alice	Hodnota ve feedu
Číslo	Desetinné číslo (6 desetinných míst)
Datum	Datum a čas v UTC
Ano/ne	Logická hodnota
Pole s více hodnotami, Tags	Text (JSON)
Hodnota, kterou nelze převést	Prázdná hodnota

Názvy tabulek a sloupců

Názvy mohou obsahovat pouze písmena, číslice a znak _ – ostatní znaky se odstraní.
Velmi dlouhé názvy se zkrátí.
V názvech se rozlišují velká a malá písmena.

Vztahy mezi tabulkami

Feed neobsahuje vztahy mezi tabulkami. V Power BI je potřeba je vytvořit ručně:

Z tabulky (sloupec)	Do tabulky (sloupec)
Tabulka typu dokumentu (`AccountingUnitId`)	`AccountingUnits` (`AccountingUnitId`)
Tabulka typu dokumentu (`OwnerId`)	`Users` (`UserId`)
Tabulka typu dokumentu (`ValidatorId`)	`Users` (`UserId`)
Tabulka typu dokumentu (`CurrentApproverId`)	`Users` (`UserId`)
Tabulka typu dokumentu (`LastApproverId`)	`Users` (`UserId`)
Tabulka položek `…_Items` (`DocumentId`)	Tabulka typu dokumentu (`DocumentId`)

graph LR
    I["Položky dokladů (…_Items)"] -- DocumentId --> D["Tabulka typu dokumentu"]
    D -- AccountingUnitId --> A["AccountingUnits"]
    D -- "OwnerId, ValidatorId, CurrentApproverId, LastApproverId" --> U["Users (UserId)"]

Podporované dotazy OData

Podporované dotazy (pro pokročilé uživatele)

Power BI načítá data automaticky, následující informace využijete pouze při vlastním sestavování dotazů nad feedem.

Podporované parametry dotazu: $filter, $select, $orderby, $top, $skip, $count=true

Nepodporované parametry dotazu: $expand, $apply, $search, $compute

Možnosti $filter:

operátory eq, ne, gt, ge, lt, le, and, or, not a závorky
porovnání s hodnotou nebo s jiným sloupcem
porovnání s prázdnou hodnotou (eq null, ne null)

Ve $filter není podporováno:

funkce (např. contains, startswith, year)
aritmetické operace
filtrování a řazení podle Tags a polí s více hodnotami

Stránkování: Jedna odpověď obsahuje maximálně 1000 řádků. Další data se načítají automaticky přes odkaz na další stránku – Power BI načte všechna data.

Příklad:

https://api.redque.com/v1/odata/AccountingUnits?$select=Name,CustomerId&$filter=IsVatPayer eq true&$orderby=Name

Pravidla a omezení

Funkci zapíná pouze Alice, v aplikaci ji nelze zapnout ani vypnout.
Feed je pouze pro čtení.
Data se obnovují jednou denně.
Feed obsahuje doklady všech účetních jednotek bez ohledu na nastavení účetních jednotek klientské aplikace.
Přihlášení je možné pouze pomocí ID klienta a hesla klientské aplikace s rolí, která vidí všechny dokumenty.
Feed neobsahuje vztahy mezi tabulkami.
Jedna odpověď obsahuje maximálně 1000 řádků (Power BI načte další stránky automaticky).

Chybové stavy

Power BI hlásí neplatné přihlašovací údaje (401)

Možné příčiny:

chybně zadané ID klienta nebo heslo
klientská aplikace není aktivní (není zaškrtnuto Aktivní)
funkce OData konektor (Power BI) není aktivní – přihlášení selže, i když jsou ID klienta a heslo správně
pro přihlášení byl použit e-mail a heslo uživatele místo údajů klientské aplikace

403 – The client application must have the ViewAllDocuments permission.

Role klientské aplikace nemá oprávnění vidět všechny dokumenty. Změňte roli klientské aplikace na vhodnou – viz Role klientské aplikace.

404 – The data of the tenant has not been prepared yet.

Data ještě nebyla připravena. Po zapnutí funkce jsou data dostupná až po prvním obnovení.

404 – Entity set '<název>' was not found.

Tabulka s tímto názvem ve feedu neexistuje. Zkontrolujte název tabulky – v názvech se rozlišují velká a malá písmena a názvy tabulek typů dokumentů se liší podle nastavení Vaší společnosti. Seznam tabulek získáte na adrese https://api.redque.com/v1/odata.

400 – nepodporovaný dotaz (např. Query option $expand is not supported.)

Dotaz obsahuje nepodporovaný parametr nebo funkci (např. $expand nebo funkci ve $filter). Hláška popisuje, co není podporováno. Přehled podporovaných dotazů naleznete v sekci Podporované dotazy OData.

Časté otázky

Jak OData konektor zapnout?

OData konektor je placená funkce, kterou zapíná Alice. Pro aktivaci kontaktujte naše obchodní oddělení. V aplikaci funkci sami zapnout nemůžete.

Mohu se v Power BI přihlásit svým e-mailem a heslem do Alice?

Ne. Pro přihlášení je nutné použít ID klienta a Heslo klientské aplikace se způsobem ověření Základní (Basic).

Proč ve feedu nevidím změny, které jsem dnes provedl?

Data ve feedu se obnovují jednou denně. Změny provedené v Alice se ve feedu projeví až po dalším obnovení.

Proč ve feedu vidím doklady všech účetních jednotek, i když má klientská aplikace nastavenou jen jednu?

Feed vždy obsahuje doklady všech účetních jednotek Vaší společnosti. Nastavení Účetní jednotka a Další účetní jednotky u klientské aplikace se na data ve feedu neuplatní.

Proč ve feedu nevidím některý doklad?

Ve feedu nejsou doklady, které se právě nahrávají, doklady bez určeného typu a smazané doklady (v koši). Nově zpracované doklady se ve feedu objeví až po dalším obnovení dat.

Co dělat, když ztratím heslo klientské aplikace?

Heslo nelze znovu zobrazit. Klientskou aplikaci smažte, vytvořte novou a v Power BI změňte přihlašovací údaje na nové.

Jak zruším přístup Power BI k datům?

U klientské aplikace odškrtněte Aktivní. Přihlášení z Power BI poté přestane fungovat.

Mohu přes feed data v Alice upravovat?

Ne, feed je pouze pro čtení.

Proč se tabulky ve feedu jmenují jinak než typy dokumentů v aplikaci?

Názvy tabulek odpovídají interním názvům typů dokumentů. Mohou obsahovat pouze písmena, číslice a znak _, ostatní znaky se odstraní a velmi dlouhé názvy se zkrátí.

Jsou v tabulce Users i klientské aplikace?

Ano, tabulka obsahuje i technické účty klientských aplikací. Poznáte je podle sloupce IsClientApplication = true, ve sloupci Email je uvedeno ID klienta.