app-notification

Opis

Bloczek app-notification służy do wysyłania powiadomień push do aplikacji mobilnych użytkowników. Tytuł i treść powiadomienia są definiowane w konfiguracji bloczka, a ich fragmenty mogą być uzupełniane bieżącymi wartościami doprowadzonymi z bloczków tag.

Bloczek nie posiada wyjść. Do działania wymaga co najmniej jednego połączenia z bloczka innego niż tag, które będzie wyzwalało próbę wysłania powiadomienia.

Bloczek zapamiętuje ostatnie wartości odebrane z bloczków tag, liczbę skutecznie wysłanych powiadomień oraz informację o ostatnim błędzie wysyłki albo blokady.

Parametry konfiguracyjne

Nazwa parametru	Wartość
`send_to_all`	Parametr obowiązkowy typu logicznego `true` albo `false`. Gdy ustawione jest `true`, powiadomienie jest kierowane do wszystkich użytkowników mających adres e-mail powiązany z kontem. Gdy ustawione jest `false`, odbiorcy są wybierani parametrem `send_to`.
`send_to`	Parametr obowiązkowy, gdy `send_to_all = false`. Zawiera listę loginów użytkowników rozdzielonych przecinkami. Niepoprawne wpisy są odfiltrowywane. Jeśli po odfiltrowaniu nie zostanie żaden poprawny login, konfiguracja jest błędna.
`send_uncompleted_messages`	Parametr obowiązkowy typu logicznego `true` albo `false`. Gdy ustawione jest `false`, bloczek nie wyśle powiadomienia, jeśli choć jeden placeholder z `title` albo `message` nie ma jeszcze odebranej wartości z odpowiedniego bloczka `tag`. Gdy ustawione jest `true`, takie powiadomienie może zostać wysłane, a brakujące miejsca zostaną zastąpione tekstem `{?}`.
`block_repeated_values`	Parametr obowiązkowy typu logicznego `true` albo `false`. Gdy ustawione jest `true`, bloczek nie wyśle kolejnego powiadomienia, jeśli pełny tytuł i pełna treść są identyczne jak w ostatnim skutecznie wysłanym powiadomieniu.
`high_priority`	Parametr obowiązkowy typu logicznego `true` albo `false`. Określa, czy powiadomienia wysyłane przez ten bloczek mają być oznaczone jako wysokiego priorytetu.
`title`	Parametr obowiązkowy. Określa tytuł powiadomienia. Wartość nie może być pusta. W tekście można używać placeholderów w postaci `{X}`, gdzie `X` oznacza numer taga, na przykład `{1}` albo `{2}`.
`message`	Parametr obowiązkowy. Określa treść powiadomienia. Wartość nie może być pusta. W tekście można używać placeholderów w postaci `{X}`, gdzie `X` oznacza numer taga.

Obsługa wejścia

Bloczek dopuszcza wiele połączeń do wejścia.

Na wejściu obsługiwane są dwa rodzaje sygnałów:

wartości pochodzące z bloczków tag, które służą do uzupełniania placeholderów {X} w title i message
wartość true pochodząca z bloczka innego niż tag, która wyzwala próbę wysłania powiadomienia

Inne sygnały z bloczków niebędących tag, takie jak false, liczby, tekst albo null, są ignorowane.

Wartości odebrane z bloczków tag są zapamiętywane jako ostatnia wartość danego numeru taga. Przy podstawianiu do tytułu i treści używana jest tekstowa reprezentacja wartości bez jednostki. Jeśli odebranej wartości nie da się przedstawić tekstowo, taka zmiana nie aktualizuje zapamiętanej wartości taga.

Bloczek obsługuje dynamiczne wejścia oznaczane przez bloczek tag:

Numer i nazwa wejścia	Opis działania
`tagX`: Wartość podstawiana do `{X}`.	Każdy placeholder `{X}` użyty w `title` albo `message` musi mieć odpowiadający mu podłączony bloczek `tag` o numerze `X`. Jednocześnie każdy podłączony bloczek `tag` musi być użyty przynajmniej raz w `title` albo `message`.

Próba wysłania powiadomienia po odebraniu wartości true przebiega w następujący sposób:

z title i message tworzona jest pełna treść przez podstawienie ostatnio odebranych wartości tagów
jeśli send_uncompleted_messages = false i brakuje choć jednej wartości taga, powiadomienie nie zostanie wysłane
jeśli send_uncompleted_messages = true, brakujące wartości zostaną zastąpione tekstem {?}
jeśli block_repeated_values = true i pełny tytuł oraz pełna treść są identyczne jak w ostatnio wysłanym powiadomieniu, wysyłka zostanie zablokowana
jeśli nie uda się wyznaczyć żadnego adresu e-mail odbiorców, wysyłka również nie nastąpi

Bloczek wymaga co najmniej jednego podłączonego źródła wyzwalającego, czyli bloczka innego niż tag. Same połączenia z bloczków tag nie wystarczą do poprawnej konfiguracji.

Wyjścia bloczka

Bloczek nie posiada wyjść.

Opis statusu bloczka

Dla poprawnie działającego bloczka opis statusu ma postać:

Notifications sent: X.

albo:

Notifications sent: X, last error: Y

gdzie:

X oznacza liczbę skutecznie wysłanych powiadomień
Y oznacza ostatni błąd lub powód zablokowania wysyłki

Pole last error może wskazywać między innymi:

brak kompletu wartości tagów przy send_uncompleted_messages = false
próbę ponownego wysłania identycznego powiadomienia przy block_repeated_values = true
brak adresów e-mail odbiorców
błąd zwrócony przez mechanizm wysyłki powiadomień

Błędy zwracane przez bloczek

Bloczek może zwracać następujące błędy:

Kod błędu	Opis błędu
`Missing parameter 'send_to_all'.`	W konfiguracji nie podano parametru `send_to_all`.
`Missing parameter 'send_to'.`	Parametr `send_to_all` ma wartość `false`, ale w konfiguracji nie podano parametru `send_to`.
`Empty 'send_to' parameter.`	Parametr `send_to` został podany, ale jest pusty.
`No valid users specified.`	Po odfiltrowaniu niepoprawnych wpisów z `send_to` nie został żaden poprawny login użytkownika.
`Missing parameter 'send_uncompleted_messages'.`	W konfiguracji nie podano parametru `send_uncompleted_messages`.
`Missing parameter 'block_repeated_values'.`	W konfiguracji nie podano parametru `block_repeated_values`.
`Missing parameter 'high_priority'.`	W konfiguracji nie podano parametru `high_priority`.
`Missing parameter 'title'.`	W konfiguracji nie podano parametru `title`.
`Empty title.`	Parametr `title` jest pusty.
`Missing parameter 'message'.`	W konfiguracji nie podano parametru `message`.
`Empty message.`	Parametr `message` jest pusty.
`Missing {X} in title or message.`	Do bloczka podłączono bloczek `tagX`, ale jego numer nie został użyty ani w `title`, ani w `message`.
`Missing tagX.`	W `title` albo `message` użyto placeholdera `{X}`, ale nie podłączono odpowiadającego mu bloczka `tagX`.
`Missing non-tag block.`	Do bloczka nie podłączono żadnego źródła wyzwalającego innego niż bloczek `tag`.

Przykłady działania

Jeśli title = Alarm w {1}, message = Temperatura osiągnęła {2}, do bloczka podłączono tag1 z ostatnią wartością Kuchnia, tag2 z ostatnią wartością 28.5, a z innego bloczka na wejście dotrze wartość true, to zostanie wysłane powiadomienie o tytule Alarm w Kuchnia i treści Temperatura osiągnęła 28.5.
Jeśli message = Czujnik {1}: {2}, ale przed wyzwoleniem wysyłki odebrano tylko wartość dla tag1, to przy send_uncompleted_messages = false powiadomienie nie zostanie wysłane.
W tej samej sytuacji, jeśli send_uncompleted_messages = true, brakująca wartość zostanie zastąpiona tekstem {?}, więc treść może przyjąć postać Czujnik Salon: {?}.
Jeśli block_repeated_values = true i dwa kolejne wyzwolenia wysyłki wygenerują dokładnie ten sam tytuł i dokładnie tę samą treść, to drugie powiadomienie zostanie zablokowane.
Jeśli send_to_all = false, a parametr send_to zawiera kilka loginów rozdzielonych przecinkami, to powiadomienie zostanie skierowane tylko do użytkowników z tej listy, dla których system potrafi wyznaczyć adres e-mail odbiorcy.