Návrh integrace O2 SMS Connector do Dynamics 365 (Dataverse)

Odesílání SMS z Dynamics 365 / Dataverse přes službu O2 SMS Connector pomocí Power Automate (varianta bez Azure a bez vlastního kódu pro mTLS).

Obsah

• 1. Cíl a kontext
• 2. Jak funguje O2 SMS Connector
• 3. Jádro problému — klientský certifikát v sandboxu
• 4. Doporučená architektura — Outbox pattern
• 5. Datový model — tabulka o2_smsmessage
• 6. Plugin (sandbox-safe)
• 7. Power Automate Flow
• 8. Security a správa secrets
• 9. Na co dát pozor
• 10. Otevřené otázky pro zákazníka
• 11. Předpoklady a registrace u O2
• 12. Reference na manuály

1. Cíl a kontext

Potřebujeme z Dynamics 365 (Dataverse) odesílat textové SMS koncovým uživatelům přes službu O2 SMS Connector. Řešení musí být:

• Asynchronní — odeslání SMS nesmí blokovat transakci uživatele.
• Odolné — když je O2 dočasně nedostupné, zpráva se neztratí.
• Bez nutnosti Azure — využíváme Power Platform (Power Automate).
• Sandbox-safe — respektuje omezení pluginů v Dataverse.

2. Jak funguje O2 SMS Connector

Služba nabízí dvě rovnocenná rozhraní ke stejné platformě (O2 Messaging Platform, „MP"):

Pro odesílání textové SMS použijeme HTTP POST na endpoint:

https://smsconnector.cz.o2.com/smsconnector/getpost/GP

Klíčové pojmy

• baID — ID business aplikace, přidělí O2 (7 číslic, MSISDN z rozsahu 199…, např. 1991123).
• AO/MT — Application-Originated / Mobile-Terminated = SMS od nás k uživateli (akce send).
• Certifikát — klientský X.509 (.p12 s privátním klíčem) pro mutual TLS. Identita aplikace = certifikát spárovaný s baID (žádný login/heslo).

Parametry akce send

Odpověď (HTTP 200, text/plain, UTF-8) je sada řádků KLÍČ=HODNOTA. Úspěch = responseType=SUCCESS, responseCode=ISUC_001. Synchronní chyby vrací HTTP 400. Naše msgID se vrací v poli refMsgID.

3. Jádro problému — klientský certifikát v sandboxu

O2 vyžaduje mutual TLS s klientským certifikátem. Plugin v Dataverse ale běží v sandboxu (isolation mode), který je pro práci s certifikátem prakticky nepoužitelný:

Další omezení: 2minutový timeout, žádná vlákna/registry/event log, synchronní volání externí služby blokuje transakci platformy.

Závěr: mTLS s klientským certifikátem přímo z pluginu Microsoft nepodporuje a v praxi to spolehlivě nezprovozníte. Certifikát musí žít mimo sandbox.

Řešení: Power Automate to umí nativně

Premium akce HTTP v Power Automate má v nastavení Authentication přímo typ Client Certificate, kde zadáte:

• Pfx — obsah .p12/.pfx souboru v Base64
• Password — password k privátnímu klíči

Connector provede mTLS handshake za vás. Žádný sandbox, žádný kód, žádné Azure.

4. Doporučená architektura — Outbox pattern

Plugin pouze vytvoří řádek v „outbox" tabulce (rychlé, sandbox-safe) a skončí. Power Automate Flow se spustí na vytvoření řádku, zavolá O2 přes mTLS a zapíše zpět stav.

Proč outbox tabulka a ne trigger přímo na business entitě

• Asynchronní — flow běží mimo transakci Dataverse.
• Odolnost — při výpadku O2 zůstane řádek Pending, lze opakovat.
• Audit/logging — historie každé SMS (text, příjemce, responseCode, refMsgID, čas).
• Decoupling — plugin jen vytvoří řádek a hned skončí, neblokuje uživatele.

Sekvenční pohled

5. Datový model — tabulka o2_smsmessage

Custom tabulka jako outbox a zároveň audit log.

6. Plugin (sandbox-safe)

Plugin nedělá nic náročného — jen zapíše řádek do outboxu. Veškerá síťová a certifikátová logika je mimo sandbox.

var sms = new Entity("o2_smsmessage");
sms["o2_tonumber"] = "+420602123456";
sms["o2_text"]     = "Vas kod je 1234";
sms["o2_status"]   = new OptionSetValue(1); // Pending
service.Create(sms);

Plugin step registrujte tak, aby zápis odpovídal vaší business logice (typicky synchronně na hlavní entitě — samotný Create řádku je levný; vlastní odeslání SMS je už asynchronní díky flow).

7. Power Automate Flow

Kroky

1. Trigger: Dataverse → When a row is added na tabulce o2_smsmessage.

2. (Volitelně) Get Secret: Azure Key Vault → načtení Pfx Base64 a hesla, nebo čtení z Environment Variables.

3. Compose – body (form-urlencoded; text musí být URL-enkódovaný):

text action=send &baID=@{variables('baID')} &toNumber=@{uriComponent(triggerOutputs()?['body/o2_tonumber'])} &text=@{uriComponent(triggerOutputs()?['body/o2_text'])} &msgID=@{guid()} &deliveryReport=FALSE &multipart=@{if(greater(length(triggerOutputs()?['body/o2_text']),160),'TRUE','FALSE')} &priority=3

(v praxi jako jeden concat() / Compose bez odřádkování)

1. HTTP akce:
2. Method: POST
3. URI: https://smsconnector.cz.o2.com/smsconnector/getpost/GP
4. Header: Content-Type: application/x-www-form-urlencoded
5. Body: výstup z Compose

6. Authentication: Client Certificate → Pfx (Base64), Password

7. Vyhodnocení odpovědi — O2 vrací text/plain řádky KLÍČ=HODNOTA. Úspěch:

text contains(body('HTTP'), 'responseType=SUCCESS')

nebo přesněji vytáhnout responseCode (ISUC_001) a refMsgID.

1. Update row v o2_smsmessage → status Sent/Failed, uložit responseCode, refMsgID a surovou odpověď.

Tok flow

8. Security a správa secrets

Konverze certifikátu .p12 → Base64 (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("cert.p12"))

9. Na co dát pozor

10. Otevřené otázky pro zákazníka

Než finalizujeme implementaci, potřebujeme od zákazníka (a částečně od O2) zodpovědět níže uvedené otázky. Jejich odpovědi rozhodnou o volbě rozhraní a konkrétní metody (HTTP GET/POST vs Web Services, a v rámci WS SimpleSmsGw.sendSms vs PPGw.send, pull vs push). Náš návrh počítá s HTTP GET/POST přes Power Automate — to je správně jen pokud odpovědi nevynutí SOAP (viz rozhodovací matice).

Slouží zároveň jako checklist na schůzku — pole na odpovědi jsou prázdná.

A. Funkční rozsah (rozhoduje o rozhraní)

B. Objem a kapacita (rozhoduje o tarifu)

C. Identita a registrace u O2

D. Certifikát

E. Odesílatel a obsah

F. Provoz

Rozhodovací matice

Mapování odpovědí na správnou metodu:

Klíčové „rozbíječe" HTTP GET/POST řešení (kvůli kterým bychom museli na Web Services): potřeba Unicode diakritiky, binary/MMS/premium zpráv, nebo push příjmu. Pokud žádný nenastane, zůstává HTTP GET/POST + Power Automate jako nejjednodušší volba.

11. Předpoklady a registrace u O2

1. Registrace aplikace u O2 — aktivační formulář, navázání na hlasové číslo, volba tarifu a kapacity, přidělení baID a denních/měsíčních limitů.
2. Certifikát — vygenerovat (O2 aplikace nebo veřejná CA: 1.CA, Verisign…), veřejnou část (.PEM) zaslat O2 ke spárování s baID, privátní (.P12) si ponechat.
3. Limity a kapacitu potvrdit s O2.

12. Reference na manuály

Stažené v adresáři docs/:

Zdroj dokumentace: https://www.o2.cz/podnikatele-a-firmy/volani/sms-connector