Adaptive Cards w Outlook - kompletny przewodnik • Tomasz Poszytek, Business Applications MVP

Adaptive Cards w Outlook – kompletny przewodnik

Table of Contents

Minęło trochę czasu, odkąd pierwszy raz pomyślałem o napisaniu tego postu. Ostatnio dostałem więcej pytań na ten temat i zdałem sobie sprawę, że rzeczywiście jest wątek o Adaptive Cards, o którym jeszcze nie pisałem. Pozwól zatem, że naprawię to niedopatrzenie przy pomocy tego kompletnego przewodnika.

Zobacz działające rozwiązanie!

Actionable Messages używające Adaptive Cards

Najpierw musisz zrozumieć, że chociaż nadal są to Adaptive Cards, które są wysyłane do Outlooka, czasami nazywane są również Actionable Messages. Są dość podobne, ale mają pewne różnice:

	Adaptive Cards	Actionable Messages
Wersja	1.3	1.0 (source)
Akcje	Http, Submit, ShowCard, ToggleVisibility	Http (dla get i post), OpenUrl. InvokeAddInCommand do otwierania add-in zadań w Outlook. DisplayMessageForm otwierania formularza odczytu wiadomości DisplayAppointmentForm do otwierania kalendarza elementu z wiadomości ToggleVisibility
Target dla wiadomości	Nie wspierane, musi być zarządzane przez host	Wspierane. Można zdefiniować URL, nagłówek i treść żądania.
ActionSet	Tak	Tak
Odświeżanie karty	Tak, ale tylko poprzez żądania z hosta.	Tak, jako odpowiedź z aplikacji odbierającej żądanie.
Autoryzacja	Bezpieczeństwo obsługiwane przez hosta, który wysyła kartę i odbiera odpowiedź.	Usługa wysyłająca karty musi być zarejestrowana i zatwierdzona przez firmę Microsoft. Odpowiedzi muszą zostać zatwierdzone przez klienta, aby potwierdzić autentyczność nadawcy.
Inne różnice	Wszystkie dobrodziejstwa pochodzące z wersji 1.0+	Input.Time nie działa, parametr hideOriginalBody do ukrywania zawartości wiadomości innej niż karta, originator przekazania parametru GUID nadawcy. correlationId do ustawienia własnego ID trackowania karty
Źródło: https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card#outlook-specific-adaptive-card-properties-and-features

Uwaga! Jak widać z powyższego porównania, Actionable Messages są rodzajem hybrydy między kartami adaptacyjnymi a starymi kartami wiadomości (Message Cards). Wciąż istnieje możliwość wysłania Actionable Message z JSON w formacie Message Card, ale nie to jest tematem tego posta.

Wymagania

Technologia nie byłaby sobą, gdyby nie było żadnych ograniczeń co do tego, kiedy i jak można ją wykorzystać. Zasadniczo istnieją pewne wersje programów Outlook i Office 365, które obsługują Actionable Messages korzystające zarówno z Message Cards lub Adaptive Cards. Dowiedz się więcej tutaj: https://docs.microsoft.com/en-us/outlook/actionable-messages/#outlook-version-requirements-for-actionable-messages.

Ważne! Technologia Actionable Messages działa wyłącznie w klientach Office 365 Outlook.

Wysyłanie Actionable Message

Krok 1, tworzenie Adaptive Card

By wysłać Adaptive Card jako Actionable Message najpierw otwórz https://adaptivecards.io/designer/ i zmień „host app” na „Outlook Actionable Messages”:

Spowoduje to automatyczne ustawienie wersji na 1.0 i zmianę walidacji schematu, aby umożliwić wstawienie wszystkich wyjątków, o których wspomniałem powyżej. Teraz zaprojektuj swoją kartę.

Ważne! Musisz zdefiniować wartość identyfikatora dla każdego pola na karcie. Będą one używane do pobierania wstawionych wartości i wysyłania ich do docelowego adresu URL:

Alternatywnie możesz zaprojektować kartę za pomocą Actionable Messages Designer: https://amdesigner.azurewebsites.net / – za pomocą tego narzędzia możesz nie tylko wyświetlić podgląd karty, aby zobaczyć, jak wygląda, ale także możesz wysłać ją do swojej skrzynki odbiorczej. Jest też zestaw gotowych do użycia szablonów. Mega!

Krok 2, zdefiniuj akcje

Pamiętaj, że Actionable Messages posiada dużo więcej akcji niż Adaptive Cards. Skoncentrujmy się na działaniu Http. Weźmy poniższy przykład:

{
            "type": "Action.Http",
            "title": "Approve",
            "url": "https://[URL-OF-TARGET-APP]",
            "id": "ac_approve",
            "style": "positive",
            "method": "POST",
            "body": "{\"comments\":\"{{ac_comments.value}}\",\"outcome\":\"approve\"}",
            "headers": [
                {
                    "name": "Authorization",
                    "value": ""
                },
                {
                    "name": "Content-type",
                    "value": "application/json"
                }
            ]
        }

Musisz zdefiniować poniższe atrybuty:

url – gdzie zostanie przesłana zawartość formularza. W moim przypadku będzie to kolejny przepływ Power Automate wyzwalany przez akcję Web Request.
method – POST czy GET? W przypadku formularza, naturalnie POST.
body – to musi być zserializowany JSON. Uwaga, możesz odwoływać się do pól na swojej karcie, używając placeholdera {{field_id.value}}.
headers – określ typ zawartości ORAZ pozostaw pusty nagłówek „Authorization”, ponieważ zapewni to, że Twoje żądanie nie będzie kolidować z mechanizmem autoryzacji systemu docelowego (source).

Kork 3, zbuduj flow do obsługi odpowiedzi

Teraz musisz zbudować przepływ uruchamiany przez wyzwalacz „When a HTTP request is received”. Określ wartość żądania Body JSON Schema na tę, którą będziesz wysyłać z Adaptive Card. W moim przypadku jest to dość proste:

{
    "type": "object",
    "properties": {
        "comments": {
            "type": "string"
        },
        "outcome": {
            "type": "string"
        }
    }
}

Teraz możesz zdefiniować dowolną logikę wewnątrz przepływu, ale ważne jest, aby dodać akcję „Response”, która wyśle potwierdzenie do Actionable Message.

Zastępowanie istniejącej Adaptive Card kartą z potwierdzeniem

Jeśli chcesz po prostu zastąpić istniejącą Adaptive Card w skrzynce odbiorczej użytkownika kartą potwierdzającą, zaprojektuj ją, a następnie skonfiguruj akcję „Response” w następujący sposób:

Dodaj nagłówek: content-type – application/json,
Dodaj nagłówek: CARD-UPDATE-IN-BODY – true
Ten nagłówek poinformuje Actionable Message, aby zastąpić istniejącą kartę, kodem karty wysłanym w treści odpowiedzi.
W Body skopiuj i wklej kod JSON Adaptive Card wysłanej jako potwierdzenie wykonania akcji.

Źródło: https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card#refresh-cards

Wysłanie notyfikacji do użytkownika

Jeśli chcesz wysłać powiadomienie z powrotem do użytkownika, ale bez faktycznego zamykania karty, użyj kodu statusu 4xx (zgodnie ze swoim scenariuszem) i:

Dodaj nagłówek: content-type – application/json,
Dodaj nagłówek: CARD-ACTION-STATUS – informacja wyświetlona użytkownikowi.

Źródło: https://docs.microsoft.com/en-us/outlook/actionable-messages/adaptive-card#reporting-actionhttp-execution-success-or-failure

Krok 4, opublikuj flow obsługujący odpowiedź

I skopiuj jego adres URL, a następnie wklej w atrybut „url” w akcjach wysyłających formularz w Adaptive Card.

Krok 5, zredaguj i wyślij Actionable Message

Teraz umieść akcję Compose wewnątrz przepływu, który będzie używany do wysyłania Actionable Message. Wewnątrz akcji Compose, umieść kod JSON Adaptive Card między tagami </script> (source):

<script type="application/adaptivecard+json">
{ JSON KARTY ADAPTACYJNEJ }
</script>

Na koniec dodaj akcję „Send an email (V2)”, przełącz ją w tryb kodu i umieść wynik akcji „Compose”:

Wyślij wiadomość do siebie i sprawdź, jak to działa! Voilla, łatwy scenariusz zrobiony.

Actionable Messages Debugger

Aby sprawdzić i zweryfikować Actionable Message, przydatny może być dodatek do programu Microsoft Outlook o nazwie „Actionable Messages Debugger”. Pomoże Ci to zidentyfikować problemy z Twoją wiadomością. Aby to zrobić, kliknij przycisk „Get Add-ins”, a następnie wyszukaj debuger i na koniec kliknij „Dodaj”:

Teraz, gdy otworzysz go dla wiadomości zawierającej Actionable Message, pokaże Ci wszystkie problemy z nią związane. Tak jak w poniższym przykładzie, w którym wysłałem Actionable Message bez identyfikatora nadawcy (originator), a więc nie od zarejestrowanego providera:

Wysyłanie Actionable Message do innych

Zasadniczo istnieją cztery scenariusze wysyłania wiadomości e-mail Actionable Message (source):

Ze swojej skrzynki do tej samej skrzynki odbiorczej – nie jest wymagana rejestracja providera. Podejście opisane powyżej.
Zdefiniowani użytkownicy testowi w ramach tego samego tenanta – rejestracja i zatwierdzenie dostawcy samoobsługowe.
Administratorzy Exchange na tenancie – zatwierdzanie przez administratora Exchange. Pozwoli na wysyłanie Actionable Messages do dowolnych użytkowników w Twoim tenancie.
Globalnie – zezwalaj na wysyłanie Actionable Message do dowolnego użytkownika w Office 365. Wymaga approvala od Microsoft.

Aby móc wysyłać Actionable Message do innych użytkowników w tenantach Office 365, musisz najpierw otworzyć „Actionable Email Developer Dashboard” (https://outlook.office.com/connectors/oam/publish), a następnie zarejestrować nowego dostawcę.

Uwaga! Rejestracja dostawcy w kontekście „Globalnym” wymaga zgody firmy Microsoft i może zająć kilka dni.

Gdy dostawca zostanie zatwierdzony (zostanie to zrobione automatycznie dla użytkowników testowych i administratorów), skopiuj wartość „Provider Id”:

I dodaj go jako dodatkowy atrybut do kodu JSON Adaptive Card:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "hideOriginalBody": true,
  "originator": "f6f1d226-abcd-asdaa-asdasd-123123123123",
  "body": [

Teraz, w zależności od wybranego zakresu, będziesz mógł wysyłać swoje wiadomości dla szerszej publiczności.

Weryfikacja odpowiedzi z wiadomości

W celu zweryfikowania, czy nadawca odpowiedzi z Actionable Message jest tym, kogo oczekujemy, zapoznaj się z technikami z drugiej części tego posta: https://poszytek.eu/en/microsoft-en/office-365-en/powerautomate-en/securing-responses-from-actionable-messages/.

I to wszystko! Jeśli masz pytania, zostaw je w komentarzach poniżej. Dziękuję 🙂

1 września, 2020