Integrace pro klienty
Integrace má být navržená jako provozní proces, ne jen sada endpointů. Klient musí vědět, co je autoritativní zdroj dat a jak se řeší chyby.
K čemu se integrace hodí
Sekce “K čemu se integrace hodí”Bez integrace jsou Knowspread a vaše ostatní systémy dvě evidence téže firmy a někdo je musí držet v souladu ručně: zakládat lidi, přesouvat je mezi skupinami, opisovat dokončení. Integrace tuto práci přesune na systémy.
- Nový kolega má účet první den. Nastoupí zaměstnanec. HR systém ho zapíše a integrace ho založí v Knowspreadu pod stabilním identifikátorem. Nikdo nepřepisuje jméno a e-mail ručně a po změně příjmení zůstane záznam týž.
- Změna oddělení se projeví ve školení sama. Zaměstnanec změní pozici. HR systém změní jeho skupinu, a protože skupiny mohou měnit přiřazení obsahu, dostane školení nového oddělení, aniž by mu ho někdo přiřazoval po jednom.
- Dokončení se propíše do evidence. Zaměstnanec dokončí povinný kurz. Váš
systém se to dozví webhookem
content_assignment_completed, nebo si to zjistí dotazem na API, a označí požadavek za splněný. Odpadá páteční export a přepisování do tabulky.
Tabulka níže tyto situace třídí podle toho, odkud kam data tečou. Ať zvolíte kterýkoli směr, začněte volbou identifikátoru: stabilní přežije změnu jména i e-mailu.
Typické integrační scénáře
Sekce “Typické integrační scénáře”| Scénář | Směr | Poznámka |
|---|---|---|
| Zakládání uživatelů | Externí systém -> Knowspread | Nutný stabilní identifikátor. |
| Aktualizace skupin | Externí systém -> Knowspread | Skupiny mohou měnit přiřazení obsahu. |
| Import obsahu nebo událostí | Externí systém -> Knowspread | Vhodné pro katalogy a blended learning. |
| Reporting dokončení | Knowspread -> externí systém | Lze řešit API dotazem nebo webhookem. |
| Webhook notifikace | Knowspread -> externí systém | Vyžaduje dostupný HTTPS endpoint. |
Identifikátory
Sekce “Identifikátory”Pro uživatele lze v různých kontextech pracovat s:
- interním ID,
- e-mailem,
personal_id,- externím ID skupiny nebo obsahu.
Pro dlouhodobou synchronizaci je nejlepší stabilní identifikátor, který se nemění při změně jména nebo e-mailu.
Webhooky
Sekce “Webhooky”Webhooky jsou odchozí notifikace z Knowspread. Aktuální model počítá s eventy:
content_assignment_created,content_assignment_completed,content_assignment_overdue,test_attempt_completed.
Endpoint klienta musí používat HTTPS. Podporované režimy autentizace jsou bez autentizace, Basic Auth a OAuth2 client credentials. Pokud je nastaven secret, je možné ověřovat podpis payloadu.