Projekt

Všeobecné

Profil

SMS notifikácie z IS Previs

V Previse bolo pridané nové rozšírenie, ktoré umožňuje zasielať SMS notifikácie. Odosielanie SMS je realizované pomocou platenej služby tretej strany (EuroSMS).

Technický popis riešenia

Na odosielanie SMS sa využíva public SMS API (viď. priložená dokumentácia poskytovateľa). Previs využíva ako spôsob pripojenia Rest-Ful rozhranie, viď. kapitola 9 dokumentácie. Využívajú sa dve volania:

  • https://as.eurosms.com/api/v3/test/one - testovanie odosielania SMS správ (HTTP POST REQUEST), pričom v tele requestu sa nachádza JSON reprezentácia odosielaných dát. Toto volanie vracia JSON response, kde sa okrem iného nachádza aj UUID danej SMS správy, ktoré ďalej slúži na zistenie statusu doručenia. Toto volanie však v skutočnosti neodošle žiadnu SMS správu a slúži na testovacie účely.
  • https://as.eurosms.com/api/v3/send/one - na odosielanie SMS správ (HTTP POST REQUEST), pričom v tele requestu sa nachádza JSON reprezentácia odosielaných dát. Toto volanie vracia JSON response, kde sa okrem iného nachádza aj UUID danej SMS správy, ktoré ďalej slúži na zistenie statusu doručenia. Toto volanie odošle správu bez diakritiky o dĺžke 160 znakov na jedno telefónne číslo.
  • https://as.eurosms.com/api/v3/status/one/UUID - na zistenie stavu doručenia konkrétnej SMS správy (HTTP GET REQUEST). UUID je v URL adrese nahradené konkrétnym UUID odoslanej SMS správy.

Procesný postup zahrňuje vytvorenie reprezentácie odosielanej SMS správy v databáze Previsu užívateľom (cez IS Previs). Následne nasleduje volanie služby PrevisAPI, ktorá preberie dátovú reprezentáciu odosielanej sms správy z databázy Previsu a vytvorí z nej požadovaný JSON objekt (v tvare viď. dokumentácia providera). Tento zakryptuje s pošle v rámci POST requestu službe PrevisAPISms. Služba PrevisAPISms, ktorá môže (ale nemusí) bežať v DMZ zóne internej siete správu dešifruje a v rámci POST requestu ju pošle na server providera (viď. predošlý odsek). Provider vráti informáciu o prijatí SMS správy na odoslanie (UUID) a táto informácia je vrátená službe PrevisAPISms, ktorá ju posunie ďalej službe PrevisAPI a tá ju zapíše k existujúcej reprezentácii odoslanej správy do databázy Previsu.
Druhou vetvou procesu je pravidelné volanie služby PrevisAPI z klientských počítačov za účelom zistenia stavu doručenia jednotlivých SMS správ. PrevisAPI preberie z databázy údaj UUID zatiaľ nedoručených správ a tieto informácie predá služne PrevisAPISms. Služba PrevisAPISms pomocou GET requestu osloví server providera a dostane odpoveď obsahujúca informácie o doručení pre jednotlivé správy. Túto informáciu služba PrevisAPISms posunie službe PrevisAPI a tá ju zapíše do databázy (k jednotlivým správam). Všetky odoslané SMS správy zostávajú uložené v databáze Previsu, vrátane informácie o doručení, resp. chybe doručenia. Grafické znázornenie procesov odosielania SMS si môžete pozrieť nižšie:

Konfigurácia poskytovateľa pre SMS

V Previse je v prvom kroku potrebné cez MENU / TMR / SMS notifikácie / SMS poskytovatelia zadefinovať poskytovateľa pre odosielanie SMS správ. Tento záznam obsahuje údaje:
  • Názov poskytovateľa - napr. EuroSMS
  • URL pre odosielanie SMS správ - napr. https://as.eurosms.com/api/v3/send/one
  • URL pre zistenie stavu - napr. https://as.eurosms.com/api/v3/status/one
  • Aktuálny poskytovateľ - logický údaj hovoriaci o tom, či je záznam o poskytovateľovi aktuálny. Aby poskytovateľ mohol byť využívaný na odosielanie SMS správ, musí byť aktuálny
  • Testovací mód - táto predvoľba prepne poskytovateľa do testovacieho módu
  • Testovacie telefónne číslo - telefónne číslo, kam budú v prípade zapnutia testovacieho módu poskytovateľa chodiť SMS správy (na odskúšanie funkcionality)
  • Secret Key - tajný kľúč, dodaný poskytovateľom pre konkrétneho zákazníka (získať sa dá po prihlásení na webe https://www.eurosms.com). Tento je uložený v databáze Previsu a je zakryptovaný pomocou AES-256 symetrického kryptovania. Tajný kľúč sa cez Previs nedá zobraziť, je možné ho len zadať, resp. znova zadať. Zadať secret key môže iba člen role admin alebo db_owner. Údaj secret key sa spolu s cieľovým telefónnym číslo, integračným ID (viď. nižšie) a textom SMS správy používa na vytvorenie digitálneho podpisu SMS správ, ktorý je súčasťou JSON reprezentácie odosielaných dát pri odosielaní SMS správ.

Konfigurácia v admin. nastaveniach

Ak už je definovaný poskytovateľ SMS, je potrebné si ho predvoliť cez MENU / Administrácia / Nastavenia / Všeobecné nastavenia, na stránke TMR (v časti SMS notifikácie). Okrem predvolenia poskytovateľa je potrebné tu zadať (bez správneho vyplnenia všetkých 3 údajov systém nebude odosielať SMS):
  • Integračné ID odosielateľa - údaj dodaný poskytovateľom (získať sa dá po prihlásení na webe https://www.eurosms.com)
  • Názov odosielateľa - krátky názov odosielateľa, max. 11 znakov, ktorý sa v prijatej SMS správe zobrazuje namiesto čísla odosielateľa správy

Konfigurácia predvolenej SMS správy

Po nakonfigurovaní v admin. nastaveniach je potrebné v systéme cez MENU / TMR / SMS notifikácie / Predvolené SMS správy vytvoriť aspoň jednu predvolenú SMS správu. Takáto správa môže obsahovať aj niektoré parametre, ktoré sú potom pri odosielaní nahradené aktuálnymi hodnotami z databázy, napr. dátum odoslania správy.

Odosielanie notifikácií

Samotné odosielanie SMS notifikácií sa realizuje v module TMR, konkrétne v MENU / TMR / Týždenný plán alebo MENU / TMR / Mesačný plán. Užívateľ označí jeden alebo viac naplánovaných odberov a na pravý klik vyberie možnosť odoslať SMS notifikácie. Následne mu systém zobrazí dialógové okno s informáciami, ktoré budú odosielané. V prípade, že niektorá zo správ presahuje 160 znakov, bude zvýraznená a odoslanie neprebehne. Odosielanie prebieha na pozadí, takže nie je potrebné na odoslanie čakať.
V prípade potreby je možné v budúcnosti túto funkcionalitu jednoducho rozšíriť a posielať z Previsu aj ďalšie typy notifikácií. Pre správne fungovanie odosielania SMS správ sú potrebné tieto ďalšie nastavenia:
  • v karte odberného miesta (resp. producenta a pod.) je potrebné vyplniť údaje Adresa pre SMS a telefónne čísla pre SMS notifikácie (na stránke TMR). V prípade, že odberné miesto nebude mať definovanú adresu pre posielanie SMS, systém použije názov odberného miesta, čo však kvôli dĺžke názvu odberného miesta môže spôsobiť, že výsledná SMS bude dlhšia ako 160 znakov a nebude ju možné odoslať.

Prehľad odoslaných správ

V MENU / TMR / SMS notifikácie / Prehľad odoslaných správ sa nachádza prehľad všetkých odoslaných SMS správ. Klikom na konkrétnu správu je možné ju opakovane odoslať. V tomto formulári je možné aj vytlačiť tlačový výstup obsahujúci vybrané SMS (je možné ich filtrovať).

SMS.API.v-3.1.15.pdf (3.18 MB) Černý Martin, 03.05.2023 14:11

SmsProcesy.pdf (253 KB) Černý Martin, 12.09.2023 16:13

SmsProcesy.png Zobraziť (501 KB) Černý Martin, 12.09.2023 16:16

Vložiť obrázok zo schránky (Maximálna veľkosť: 100 MB)