Integracja Microsoft Teams z Microsoft Graph

Dotyczy wersji 2020.1.x; autor: Tomasz Słuszniak

 

Wprowadzenie

Realizując projekty w WEBCON BPS można ułatwić komunikację wykorzystując Zespoły w Microsoft Teams. Zamiast dodawać nowy Team ręcznie, można skorzystać z automatyzacji procesów biznesowych, którą zapewnia WEBCON BPS. Na przykład, można ustawić taką automatyzację podczas rejestrowania nowego obiegu Projektu. Z pomocą przyjdzie platforma Microsoft Graph. Tworzenie zespołu podzielone jest na dwa etapy:

1. Utworzenie grupy Office365
2. Utworzenie zespołu na bazie grupy

Aby połączyć WEBCON BPS z Microsoft Graph należy utworzyć połączenie dla REST WebSerwisu. Konfiguracja połączenia została opisana w artykule https://kb.webcon.pl/integracja-z-aad-przy-pomocy-akcji-wywolania-rest-oraz-microsoft-graph/.

Przykładowy proces Projektowy składa się z kilku pól:

1. Nazwa projektu
2. Opis projektu
3. Project Manager
4. Zespół
   1. Pracownik
   2. Rola w zespole
      

 

Tworzenie zespołu

Aby utworzyć nowy zespół, należy zacząć od utworzenia grupy Office 365. Do utworzenia tej grupy wykorzystano metodę https://graph.microsoft.com/beta/groups (szczegółowy opis wywołania tej metody dostępny pod adresem: https://docs.microsoft.com/en-us/graph/api/group-post-groups?view=graph-rest-beta&tabs=http).

W pierwszej kolejności należy skonfigurować akcję wywołania REST WebService:

 

W akcji należy wybrać połączenie do MS Graph:

 

W zakładce “Request data” należy wpisać adres metody (/beta/groups) oraz metodę http (POST):

 

Następnie należy przejść do zakładki JSON i uzupełnić zestaw danych jakie zostaną przekazane do Web Service’u:

 

Nazwa grupy (atrybut „displayName”) powinna być zgodna z polityką nazywania grup w organizacji. W zależności od ustawień, nazewnictwo grup może wymagać ustawienia specyficznego prefixu lub sufixu. Szczegółowy opis przedstawiono w artykule: https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/groups-naming-policy

Podczas tworzenia grupy bez wymaganego prefixu Microsoft Graph zwróci stosowny komunikat oraz zaproponuje zgodną z polityką nazwę.

{"error": {

    "code": "Request_BadRequest",

    "message": "The property is missing a required prefix/suffix per your organization's Group naming requirements.",

    "details": [

      {

        "target": "displayName",

        "suggestedPropertyValue": "Grp_BPS MSGraph Integration",

        "code": "MissingPrefixSuffix"

      }

    ]

  }

}

Tworząc grupę, możemy wskazać również jej członków. Wykorzystamy do tego listę pozycji, na której wybieramy pracowników wraz z rolami. Lista członków grupy przekazywana do Microsoft Graph powinna wyglądać w następujący sposób:

"members@odata.bind": [

   "https://graph.microsoft.com/beta/users/t.sluszniak@webcon.pl",

   "https://graph.microsoft.com/beta/users/t.green@webcon.pl"

 

Aby utworzyć taką listę należy skorzystać z atrybutu technicznego wiele wierszy tekstu.

 

Akcja za pomocą zapytania SQL odpytuje listę pozycji i scala wszystkie rekordy oddzielając je przecinkiem, generując odpowiedni dla wywołania metody Microsoft Graph format. Tak przygotowany atrybut możena przekazać podczas tworzenia grupy w następujący sposób:

 

Ostatnią czynnością do wykonania w konfiguracji akcji tworzącej grupę Office 365 jest konfiguracja przetwarzania odpowiedzi po wywołaniu metody Web Serwisu. W zakładce „Response” ustawiono przypisanie ID utworzonej grupy do atrybutu technicznego. W zakładce „Response” widoczne są wszystkie atrybuty jakie zostaną zwrócone przez Web Serwis po poprawnym jego wywołaniu. Interesuje nas jedynie atrybut „id”, a docelowy atrybut w WEBCON BPS to „_Group ID”. ID grupy zostanie wykorzystane w kolejnym kroku – tworzenia zespołu.

 

Tworzenie zespołu na podstawie grupy

Do utworzenia zespołu w Microsoft Teams wykorzystano kolejną metodę dostępną w Microsoft Graph – https://graph.microsoft.com/beta/groups/{id}/team (szczegółowy opis wywołania tej metody dostępny pod adresem: https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta#example-4-create-a-team-from-group).

Microsoft zaleca, aby w przypadku tworzenia Zespół na podstawie nowo tworzonej grupy, odczekać około 15 min po jej utworzeniu z uwagi na opóźnienia wynikające z replikacji danych. W przeciwnym wypadku istnieje możliwość otrzymania błędu 404.

W celu utworzenia zespołu z wymaganym przez Microsoft opóźnieniem, wykorzystano w BPS akcje wywoływane „Na timeout”.

 

Timeout uruchomi akcję tworzącą zespół 3 razy. Każde uruchomienie będzie poprzedzone 5 minutową przerwą. Rekomendowany przez Microsoft czas 15 min, to maksymalny czas po jakim tworzenie zespołu będzie możliwe. Często zdarza się jednak, że zespół może zostać utworzony już po upływie pierwszych 5 min.

Konfiguracja akcji tworzenia zespołu, wykorzystuje ten sam typ akcji co w przypadku tworzenia nowej grupy – Akcja wywołania Web Serwisu REST. W akcji wykorzystano to samo połączenie, jednak zmienią się dane w pozostałych zakładkach. Pierwsza zmiana, to adres wywoływanej metody:

 

Ustawiamy adres „/beta/teams” oraz metodę http na „POST”.

W zakładce „JSON” należy wskazać grupę, dla której będzie utworzony Zespół oraz opcjonalnie można utworzyć w Zespole dodatkowy kanał, np. z zakładką wyświetlającą formularz projektu z WEBCON BPS.

 

1. Szablon, na bazie którego zostanie utworzony nowy zespół. Lista dostępnych szablonów dostępna jest pod adresem: https://docs.microsoft.com/en-us/MicrosoftTeams/get-started-with-teams-templates#what-are-base-template-types
2. Grupa, dla której zostanie utworzony zespół. Tu wykorzystano ID zapisane podczas tworzenia grupy Office 365.
3. Kanały – https://docs.microsoft.com/en-us/graph/api/team-post?view=graph-rest-beta#example-5-create-a-team-from-a-group-with-multiple-channels-installed-apps-and-pinned-tabs

Kolejną zakładką jest zakładka „Response”. Jednak w przypadku tworzenia nowego zespołu, nie ma potrzeby zapisywania jego ID, ponieważ zgodnie z dokumentacją, każdy zespół ma ten sam identyfikator co grupa, do której zespół został utworzony (https://docs.microsoft.com/en-us/graph/api/resources/team?view=graph-rest-beta).

Dlatego na potrzeby wywołania akcji tworzącej zespół, można ograniczyć jej niepotrzebne wykonywane np. w momencie, gdy zespół został utworzony podczas pierwszej iteracji timeoutu. Kolejne wykonania akcji nie będą konieczne, dlatego w zakładce „Response” można zapisać np. nagłówek „Location” do jakiegoś technicznego atrybutu:

 

a następnie skonfigurować ograniczenie wykonania akcji, aby wykonywała się tylko w przypadku, gdy techniczny atrybut jest pusty:

 

 

Przykład działania

Na potrzeby realizacji integracji z Microsoft Graph utworzono przykładowy projekt. Na formularzu obiegu Projektowego należy uzupełnić wszystkie wymagane atrybuty. Uzupełnienie listy „Team” pozwoli na przypisanie wszystkich wskazanych tu osób jako członków grupy oraz zespołu.

 

Po przejściu do kolejnego kroku, zostanie uruchomiona akcja tworząca grupę Office 365, oraz zostanie uruchomiony timeout tworzący zespół.

 

Po utworzeniu zespołu, wszyscy członkowie dostaną informację o dodaniu ich do zespołu w aplikacji Microsoft Teams oraz mailowo.

Jako efekt działania akcji wywołania Web Serwisu Microsoft Graph otrzymano utworzony w aplikacji Microsoft Teams Zespół wraz z kanałem zawierającym formularz projektu, z którym powiązany jest Zespół.

 

 

Integrację procesu Projektowego z Microsoft Teams można dodatkowo rozszerzyć np. o informowanie członków zespołu o aktualizacji danych w obiegu, wysyłając im wiadomość: https://docs.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-beta&tabs=http.