{{tag> topic module notifications sms email notification idm-ntf }}

====== Modules - Notification [ntf] ======

<note important> This is a **paid** module. If you're interested, please contact your consultant.</note>

Modul notifikací obsahuje zjednodušený mechanismus konfigurace notifikací. Přesněji ulehčuje práci administrátora v těchto ohledech:
  * definovat události, na které má reagovat notifikace (například změny nad uživatelem),
  * definovat pravidla, při kterých se má notifikace odeslat (například změna stavu uživatele),
  * upravovat topic pro jednotlivé notifikace,
  * jednoduše vypínat a zapínat jednotlivé konfigurace,
  * definovat více druhů notifikací pro jednu událost a jedno pravidlo.

<note important>Modul notifikací je zatím v první fázi vývoje. Modul neobsahuje vlastní agendu konfigurací. Konfiguraci probíhá výhradně pomocí číselníkových hodnot.</note>

Inicializace modulu notifikací [idm-ntf] je zcela automatizovaná. Po správné instalaci modulu do IdM se provede prvotní konfigurace modulu a nastavení všech konfigurací bez potřeby zásahu administrátora.

{{ :devel:documentation:ntf-module-001.drawio.png |}}

===== Version =====

^ Version  ^ Compatible with product  | **Notes**                    |
| 12.0.0    | 12.3.4                   | First module implementation for 12.x.x IdM  |
| 14.0.0    | 14.10.0                   | First module implementation for 14.x.x IdM   |
| 14.0.1    | 14.10.0                   | Bug fixing                          |

//"Compatible with the product" means that this is the recommended product version.//


===== Supported notification types  =====

Aktuálně modul notifikací podporuje notifikace pouze na následujících typech objektů/entit:
  * Uživatelé (IdmIdentity).
  * Provisioning operace (SysProvisioningOperation).

<note tip>Podpora dalších tipů objektů není pouze konfigurační, ale vyžaduje implementaci mechanismu na backendu aplikace.</note>

Pro každý podporovaný typ objektu vždy platí, že notifikace může reagovat na jakoukoliv změnu atributu pro daný objekt. Příklady:
  * (IdmIdentity) při změně stavu uživatele,
  * (IdmIdentity) při změně uživatelského jména uživatele,
  * (SysProvisioningOperation) při propisu hodnoty description do systému,
  * (SysProvisioningOperation) při propisu skupin do systému,


===== Lifecycle of sending notification =====

Notifikace jsou v aktuální verzi modulu striktně odesílané pouze při vyvolání změny objektu a to vždy pro každý objekt zvlášť. Pokud tedy například synchronizace/HR process změní stav uživatele z validního stavu (VALID) na stav odešel (LEFT) odešle se notifikace až v moment změny nikoliv dopředně.

Zároveň notifikace nejsou kumulované. Pro každou změnu se odešle jedna notifikace byť příjemce je stejný.

<note important>Modul notifikací zatím **nepodporuje** dopřené notifikace - XY dní před danou změnou.</note>

==== Příklad odeslání notifikace na změnu stavu ====

Následující příklad popisuje notifikaci na změnu atributu uživatele a notifikování například nadřízeného.

V číselníků notifikací máme odpovídající konfiguraci, která znamená, že při každé změně stavu uživatele ze stavu Validní na stav Vyňat z ev. počtu dojde k odeslání emailové notifikace nadřízenému daného uživatele.

  * Z personálního systému přichází informace ohledně změnu stavu jediného úvazku (IdmIdentityContract) daného uživatele,
  * změna úvazku znamená změnu stavu (STATE) úvazku z hodnoty NULL na hodnotu Vyňat z ev. počtu (EXCLUDED),
    * {{:devel:documentation:f39u82vt.png?600 |}}
  * personální process v IdM (HrContractExclusionProcess) automaticky přepočítá stav uživatele a vyhodnotí změnu atributu Stav (STATE) nad uživatelem (IdmIdentity),
    * {{:devel:documentation:4wdmywgt.png?600 |}} 
  * personální process vyhodnocuje změnu stavu (STATE) z hodnoty Validní (VALID) na stav Vyňat z ev. počtu (DISABLED) a zároveň k deaktivaci samotného uživatele (DISABLED) z hodnoty FALSE na TRUE,
    * {{:devel:documentation:emm0mdda.png?600 |}}
  * po úspěšném uložení uživatele s novým stavem dochází k odchycení této události modulem notifikací,
  * modul notifikací pro tuto událost vyhodnocuje všechny platné pravidla a při jejich splnění odesílá dle konfigurace notifikaci.
    * {{:devel:documentation:8rrgsow9.png?600 |}} 

{{ :devel:documentation:ntf-module-002.drawio.png |}}

==== Příklad odeslání notifikace na změnu atributů při provisioningu ====

Následující příklad popisuje notifikaci na změnu atributu na koncovém systému. Notifikace je například odeslána na uživatele s definovanou rolí.

V číselníků notifikací máme odpovídající konfiguraci, která znamená, že při každé změně hodnoty atributu Popis (description) na koncovém systému dojde k odeslání emailové notifikace na uživatele s přiřazenou rolí.

  * Na koncovém systému IdM spravuje atribut description. Tento atribut je zároveň 1:1 namapován na standardní atribut uživatele Popis (description),
    * {{:devel:documentation:zd9av1ft.png?600 |}}
  * v IdM dochází ke změně atributu Popis na uživateli,
    * 
  * změna tohoto atributu vyvolá propis na koncový systém,
    * 
  * modul notifikací zachytí úspěšně provedenou provisioning operaci a následně odesílá notifikaci.
    * {{:devel:documentation:teqbokur.png?600 |}}


==== Installation ====

This section describes the installation process of the Technical Accounts module, including its activation, required prerequisites, access rights configuration, and integration with target systems. It serves as a starting point for administrators when introducing the module into the IdM environment.

====  Configuration ====

<note tip>Modul notifikací nevyžuje žádnou specifickou konfiguraci po instalaci modulu (například konfigurační položky, tvorba číselníku atd)</note>

=== Čísleník: Entity types [ntf-entity-type] ===

{{ :devel:documentation:el5pxyci.png?500|}}

Tento číselník je automaticky vytvořen při startu aplikace na základě existence modulu idm-ntf.

<note warning>Tento číselník prosím neupravujte manuálně.</note>

V číselníku jsou obsaženy všechny objekty/entity, pro které je možné konfigurovat odesílání notifikací prostřednictvím modulu notifikací. Aktuálně jsou v modulu podporované následující objekty/entity:

  * Uživatelé (IdmIdentity),
  * Provisioning operace (SysProvisioningOperation).

=== Čísleník: Entity events [ntf-entity-event] ===

{{ :devel:documentation:hph9gxsw.png?500|}}

Tento číselník je automaticky vytvořen při startu aplikace na základě existence modulu idm-ntf.

<note warning>Tento číselník prosím neupravujte manuálně.</note>

V číselníku jsou obsaženy všechny typy událostí, které je možné kontrolovat/odchytávat v modulu notifikací. Aktuálně se jedná o následující typy událostí:
  * Vytvoření (CREATE),
  * Smazání (DELETE),
  * Aktualizace (UPDATE).

=== Čísleník: Notification code list [ntf-notification] ===

{{ :devel:documentation:ikpiavdb.png?500|}}

Tento číselník je automaticky vytvořen při startu aplikace na základě existence modulu idm-ntf. Číselník obsahuje hlavní definici notifikací. Jedná se o jedinou konfigurační část modulu, kterou je možné z pohledu administrátora editovat/upravovat.

Každá číselníková hodnota obsahuje následující atributy:
  * Entity type
    * Určení pro jaký typ objektu/entitu se daná konfigurace notifikace bude odesílat.
  * Event type
    * Typ události, pro kterou se bude daná konfigurace vyhodnocovat.
  * Form projection
    * Formulářová projekce/Typ uživatele. Aktuálně se dá použít pouze pro objekt/entitu IdmIdentity. Omezuje pro jaký typ uživatele se bude konfigurace notifikace vyhodnocovat.
  * System
    * Definice systému - jedná se o omezení pouze pro definovaný systém. Aktuálně se dá použít pouze pro objekt/entitu SysProvisioningOperation.
  * Rules
    * Definice pravidel pro danou konfiguraci. Aktuálně je podporované pouze jedno pravidlo na jednu konfiguraci. Více o pravidlech viz samostatná sekce.
  * Rules by script
    * Definice pravidel pomocí skriptu. Místo výše uvedených pravidel lze nakonfigurovat podmínku dané konfigurace pomocí skriptu. Více o skriptu viz samostatná sekce.
  * Topic
    * Standardní konfigurace notifikace - kód skriptu na který se při splnění podmínek pošle notifikace.
  * Level
    * Standardní konfigurace notifikace - označení level určuje zda notifikace bude SUCCESS, WWARNING atd. 
  * Send to identity itself
    * Konfigurace určuje zda se při splnění podmínek daná notifikace odešle na identitu samotnou.
  * Send to manager
    * Konfigurace určuje zda se při splnění podmínek daná notifikace odešle na nadřízeného daného uživatele.
  * Send to identities
    * Konfigurace určuje zda se při splnění podmínek daná notifikace odešle na zde uvedený vícehodnotový seznam identit z IdM.
  * Send to roles
    * Konfigurace určuje zda se při splnění podmínek daná notifikace odešle na zde uvedený vícehodnotový seznam rolí z IdM.
  * Recipients by script
    * Konfigurace určuje zda se při splnění podmínek daná notifikace odešle na seznam uživatelů vracených skriptem. Více viz samostatná sekce ohledně skriptů.
  * Disable
    * Určuje zda bude daná konfigurace vyhodnocena nebo nikoliv. 


==== Rules ====

V následující sekci je popsán způsob vyhodnocování pravidel pomocí skriptu a pomocí pseudo syntaxe.

<note tip>Aktuální způsob definice pravidel v modulu notifikací je příprava na plnohodnotnou agendu konfigurací notifikací.</note>



=== Rules ===

<note important>V aktuální verzi modulu 14.x.x platí omezení pouze na jedno pravidlo pro jednu konfiguraci.</note>


<well size="sm">
<text background="primary">EAV</text><wrap hi>:</wrap><text background="success">myProjectEavCode</text><wrap hi>:</wrap><text background="warning">valueA</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">valueB</text>
</well>
//Výše uvedený příklad ukazuje pravidlo, které se vyhodnocuje pro EAV atribut s kódem myProjectEavCode a pouze při změně z hodnoty valueA na hodnotu valueB.//


Uvedená pravidla mohou obsahovat následující části:
  * <text background="primary">Definice typu atributu.</text>
  * <text background="success">Kód atributu</text>
  * <wrap hi>Oddělovač.</wrap>
  * <text background="warning">Hodnota ze které je pravidlo vyhodnocováno.</text>
  * <wrap em>Změnový oddělovač.</wrap>
  * <text background="danger">Hodnota na kterou je pravidlo vyhodnocováno.</text>


V pravidlech je zároveň možné použít následující modifikátory:
  * Wild card - "*",
    * umožňuje definovat změnu z jakékoliv hodnoty, nebo změnu na jakoukoliv hodnotu.
  * null,
    * označení, že daná nebyla dříve vyplněna, nebo se daná hodnota smazala.
  * Always - "!"
    * Označení, že se daná notifikace odešle pokaždé bez ověřování změn.
  * Změna - "CHANGED"
    * Označení, že se daný atribut změnil. Nevyhodnocuje se z jaké hodnoty na jakou.

== Příklady pravidel v praxy ==



^ Pravidlo  ^Typ pravidla ^Popis  |
|<text background="primary"></text><wrap hi></wrap><text background="success">firstName</text><wrap hi>:</wrap><text background="warning">John</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">Johny</text>|Standardní atribut identity|Pravidlo popisuje změnu standardního atributu firstName uživatele z hodnoty John na Johny. Jiné změny atributu firstName nebudou vyhodnoceny jako splněné.   |
|<text background="primary">EAV</text><wrap hi>:</wrap><text background="success">clinicCode</text><wrap hi>:</wrap><text background="warning">100</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">200</text>|EAV atribut identity|Pravidlo popisuje změnu EAV atributu s kódem clinicCode, kde se hodnota tohoto atributu musí změnit z hodnoty 100 na 200. Pro všechny ostatní změny se vyhodnocení neprovede.|
|<text background="primary">EAV</text><wrap hi>:</wrap><text background="success">alternateEmail</text><wrap hi>:</wrap><text background="warning">john@example.tld</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">johny@externist_example.tld</text>|EAV atribut identity|Pravidlo popisuje změnu EAV atributu s kódem alternateEmail, kde se hodnota tohoto atributu musí změnit z hodnoty john@example.tld na johny@externist_example.tld|
|<text background="primary">EAV</text><wrap hi>:</wrap><text background="success">supervisor</text><wrap hi>:</wrap><text background="warning">*</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">true</text>|EAV atribut identity|Pravidlo popisuje změnu EAV atributu s kódem supervisor z jakékoliv hodnoty ("*") na hodnotu "true"|
|<text background="primary"></text><wrap hi></wrap><text background="success">email</text><wrap hi>:</wrap><text background="warning">*</text><wrap em><nowiki>-></nowiki></wrap><text background="danger">null</text>|Standardní atribut identity|Pravidlo popisuje změnu standardního atributu email z jakékoliv hodnoty na prázdnou (null) hodnotu. Tedy smazání atributu.|
|<text background="primary"></text><wrap hi></wrap><text background="success">externalCode</text><wrap hi>:</wrap><text background="warning">CHANGED</text><wrap em><nowiki></nowiki></wrap><text background="danger"></text>|Standardní atribut identity|Pravidlo popisuje změnu standardního atributu personální číslo (externalCode) na jakoukoliv hodnotu.|


=== Rules by script ===
 
==== Recipients ====

=== Recipients by script ===

==== Developer guide ====

=== Executor ===

=== Cache ===