Kihagyás

Teams Bot regisztráció és konfiguráció

1. Domain létrehozása a bot számára

A Teams Bot-tal csak HTTPS protokollon keresztül képes kommunikálni a Microsoft Teams, ezért fontos hogy a bot számára is regisztráljunk egy domain-t a projektünkön.

Ezt a Route 53-ban tudjuk megtenni az itt leírt módon.

Az elnevezési konvenciót tekintve kövessük az itt leírtakat. Az ${alkalmazás} placeholder javasolt értéke a Teams Bot esetén: bot.

2. Teams Bot létrehozása és konfigurálása

2.1 Teams Bot regisztráció

  1. Nyissuk meg ezt az oldalt: Bot Framework - New Bot
  2. Jelentkezzünk be a jumpcload felhasználónkkal.

  3. A Bot profile szekcióban az alábbi mezőket kötelező kitölteni (értékük tetszőleges, de célszerű a projekt nevét beletenni az egyértelműség kedvéért):

    1. Icon: Kattintsunk az Upload custom icon linkre és töltsük fel a bot repository manifest mappájában található icon-color.png-t.
    2. Display name: ${projekt-név} Bot
    3. Bot handle: ${projekt-név}Bot

    Példa

    BotProfile

  4. A Configuration szekcióban adjuk meg a Messaging endpoint mezőben a bot elérhetőségét. (Fontos, hogy az api/messages-t is tartalmaznia kell az URL-nek.) Pl.: https://bot.${projekt-név}.develop.dev.gbsolutions.io/api/messages

  5. Ezen kívül a Configuration szekcióban az App type legördülő mezőben a Multi Tenant érték legyen kiválasztva.

  6. Szükség lesz egy Microsoft App ID-ra. Amennyiben még nem rendelkezünk ilyennel, generáljuk le a Create Microsoft App ID and password gombbal: CreateMicrosoftAppIDButton

    1. A megnyíló Alkalmazásregisztrációk képernyőn kattintsunk az Új regisztráció-ra.

      AppRegistration

    2. Az Alkalmazás regisztrálása képernyőn adjuk meg az alkalmazás nevét, és válasszuk ki a Fiókok bármely szervezeti címtárban (bármely Azure AD-címtár – többvállalatos) opciót.

      AppRegistrationConfig

    3. Végül kattintsunk a Regisztráció gombra.

    4. Ekkor megnyílik a frissen regisztrált alkalmazásunkhoz tartozó konfigurációs képernyő, ahol az Alapvető adatok szekcióban jegyezzük fel az Alkalmazás (ügyfél) azonosítója mező értékét (Ez a Microsoft App ID amit az 7. pontban meg kell adni):

      ClientID

    5. Szintén az Alapvető adatok szekcióban kattintsunk a Tanúsítvány vagy titkos kód hozzáadása linkre.

      AddCert

    6. A megnyíló képernyőn kattintsunk az Új titkos ügyfélkód gombra.

      AddCertButton

    7. A megnyíló Titkos ügyfélkód hozzáadása panelon adjuk meg a tanúsítvány Leírás-át és Lejárat-át, majd kattintsunk a Hozzáadás gombra.

      Példa

      AddCertConfig

    8. A létrejött tanúsítványnak mentsük el az értékét, mert arra szükségünk lesz a továbbiakban.

      AppCertValue

    9. Ezt követően bezárhatjuk az Azure oldalt.

  7. A Configuration szekcióban adjuk meg a Microsoft App ID-t, a Paste your app ID below to continue alatti mezőben.

  8. Az Admin szekcióban az Owners mezőbe vesszővel elválasztva adjuk meg azon projekt tagok email címét, akiket szeretnénk, hogy szerkesztési joguk legyen a Bot-hoz.
  9. Pipáljuk be, hogy elfogadjuk a felhasználási feltételeket, majd kattintsunk a Register gombra.

2.2 Teams Bot konfiguráció

  1. Nyissuk meg ezt az oldalt: Bot Framework - Bots
  2. Keressük ki az általunk létrehozott botot és kattintsunk rá.

  3. A megnyíló Connect to channels képernyőn alapértelmezetten a Direct Line és Web Chat channelek vannak hozzáadva, amikre nekünk nincs szükségünk, így töröljük őket:

    ConnectToChannels

    Az alábbi lépéseket a Direct Line és Web Chat channel-re is hajtsuk végre!

    1. Kattintsunk az adott channel Actions oszlopában található ceruza ikonra.

    2. A megnyíló képernyőn kattintsunk az Add new site doboz jobb felső sarkában található kuka ikonra.

      DeleteWebChat

    3. A felugró pop-up képernyőn kattintsunk a Done gombra.

  4. A Bot Framework - Bots oldalon, az Add a featured channel szekcióban válasszuk ki a Microsoft Teams-t.

    AddFeaturedChannel

  5. A megnyíló képernyőn nem szükséges semmit beállítánunk, csak kattintsunk a bal alsó sarokban található Save gombra.

  6. Ha mindent jól csináltunk, az alábbi módon kell kinéznie a Connect to channels képernyőnek:

    ConnectToChannelsFinal

3. Teams Bot integráció

3.1 Microsoft Teams integráció

3.1.1 Manifest package létrehozása

  1. Klónozzuk ki a bot repository-t.
  2. A repo manifest mappájában nyissuk meg a manifest.json-t.
  3. Cseréljük ki a MICROSOFT_APP_ID placeholderek értékét a Teams Bot regisztráció lépésben létrehozott Microsoft App ID-ra.
  4. Cseréljük ki a BOT_NAME placeholderek értékét a projektspecifikus botunk nevére.
  5. Mentsük el a fájlt a módosításainkkal.
  6. A manifest mappában található 3 fájlt (2 db .png és egy 1 db .json) csomagoljuk össze egy darab manifest.zip archív fájlba. Fontos, hogy ne legyen benne extra manifest mappa, csak a 3 fájlt tartalmazza!
  7. Szükség esetén ezen az oldalon validálni tudjuk az elkészült archív fájlunkat: AppValidation.
  8. A módosított manifest.json fájlt, és az elkészült manifest.zip archív fájlt pusholjuk is fel a repository-ba, hogy szükség esetén elérhető legyen.

3.1.2 Custom App hozzáadása a Teams-hez

Csevegés létrehozása a Bot számára

Mielőtt a botot hozzáadnánk a Teams-hez, hozzunk létre egy csoportos csevegést, a projekt tagjai számára „${projekt-név} Bot“ névvel, és ehhez a csevegéshez adjuk hozzá az alábbi lépésekkel a botot.

Javasoljuk, hogy a Teams Bot-ot ne a daily stand-up chathez adjuk hozzá a projekten, hanem csináljuk erre egy dedikált csoportos csevegést, hogy ne a stand-up chat legyen bot üzenetekkel spammelve.

  1. Nyissuk meg a Microsoft Teams alkalmazást.
  2. Bal oldalt válasszuk ki az Alkalmazások funkciót.

  3. A bal alsó sarokban válasszuk ki az Alkalmazások kezelése menüpontot.

    AppManagement

  4. Az Alkalmazások kezelése képernyőn kattintsunk az Alkalmazás feltöltése gombra.

    AppManagementUploadButton

  5. Az Alkalmazások feltöltése képernyőn válasszuk az Egyéni alkalmazás feltöltése opciót.

    AppManagementUpload

  6. A felugró ablakban tallózzuk ki a Manifest package létrehozása lépésben létrehozott manifest.zip fájlunkat.

  7. A megnyíló ablakban kattintsunk a Hozzáadás gomb melletti kis nyilacskára, és válasszuk ki a Hozzáadás csevegéshez opciót.

    AddToConversation

  8. A keresőben válasszuk ki a bot számára létrehozott csevegést, és kattintsunk a Robot beállítása gombra.

  9. Fontos, hogy ahhoz, hogy egy csevegésen belül tudjunk utasítást adni a botnak meg kell tagelni őt a chat üzenetben: @BotNeve utasítás

    Példa

    HelloExample

Microsfot Teams hiba a hozzáadás során

Előfordulhat, hogy a Teams azt írja a hozzáadás után, hogy valamilyen hiba történt, de a hozzadás ilyenkor is sikeres, egyszerűen indítsuk újra ilyen esetben a Teams-t.

Teams Bot hozzáadása saját magunknak

Privát csevegésként a Hozzáadás gombbal tudjuk saját magunk számára hozzáadni a Teams-hez a botot.

AddToConversation

Ilyenkor a Teams Bot-nak írt üzeneteket csak a mi fogjuk látni. Ez jól jöhet olyankor, ha valamit tesztelünk a bot-on és nem akarjuk a csoportos csevegést teleszemetelni a kísérletezéshez beírt üzenetekkel.

Bot többszöri hozzáadása

A botot bármennyi chathez hozzáadhatjuk, ezért bátran adjuk hozzá magunknak és a projekt számára létrehozott csoportos csevegéshez is. Egyszerre csak egyszer adja hozzá ugyanahhoz a csevegéshez, így nem kell attól félnünk, hogy valahová véletlenül kétszer adjuk hozzá.

3.2 Alkalmazás konfiguráció

A tesztkörnyezetünkön található /opt/project/infrastructure/config/bot-service/application.yml fájl tartalma az alábbi legyen: 

MicrosoftAppId: ${microsoft-app-id}
MicrosoftAppPassword: ${microsoft-app-password}
bot:
  authorization:
    roles:
      operators: ${operators}
      developers: ${developers}
      testers: ${testers}
      business: ${business}
  teams:
    group-message:
      default-group-conversation-id: ${group-conversation-id}
  gitlab:
    access-token: ${gitlab-access-token}
    projects:
      main:
        backend: ${backend-repo-útvonal}
        frontend: ${frontend-repo-útvonal}
        api: ${api-repo-útvonal}
      bot:
        backend: ${bot-repo-útvonal}
  jira:
    project-tag: ${jira-project-tag}
    username: ${jira-username}
    access-token: ${jira-access-token}

3.2.1 Microsoft App paraméterek

A ${microsoft-app-id} placeholder helyére az itt létrehozott Microsoft App ID-t kell behelyettesíteni.

A ${microsoft-app-password} placeholder helyére az itt létrehozott tanúsívány értékét kell behelyettesíteni.

3.2.2 Az roles paraméterek

A ${operators}, ${developers}, ${testers}, ${business} placeholderek helyére, a megfelelő projekt tagok email címének @ előtti részét kell ,-vel elválasztva behelyettesíteni.

Példa helyes roles konfigurációra

bot:
  authorization:
    roles:
      operators: bela.operator
      developers: istvan.developer, csaba.developer, jozsef.developer 
      testers: ferenc.tester, peter.tester
      business: laszlo.business, denes.business
Ahol a developers paraméterben megadott csapattagok email címe az alábbi:

  • istvan.developer@intuitech.studio
  • csaba.developer@intuitech.studio
  • jozsef.developer@intuitech.studio

Amennyiben valamelyik szerepkörhöz nem kívánunk csapattagot hozzáadni, a paraméter értékét egyszerűen hagyjuk üresen.

Példa

bot:
  authorization:
    roles:
      operators: bela.operator
      developers: istvan.developer, csaba.developer, jozsef.developer 
      testers: 
      business:

3.2.3 A default-group-conversation-id paraméter

Erre a paraméterre azért van szükség, mert a bot akkor tud a megfelelő csoportos csevegésbe üzenetet küldeni, ha beállítjuk neki az adott csevegés „conversation id“-ját.

Ezt a paramétert az első Bot indítás előtt hagyjuk üresen.

Amennyiben már fut a Bot a környezetünkön, és hozzáadtuk a Teams-hez is, akkor abban a csevegésben, amelyhez a Bot-ot hozzáadtuk, a setup paranccsal kiírathatjuk a „conversation id“-t.

Ezt a „conversation-id“-t kell a ${group-conversation-id} placeholder helyére behelyettesíteni.

Ne felejtsük el a Bot alkalmazást újraindítani, miután az application.yml-be beállítottuk a ${group-conversation-id}-t.

3.2.4 A gitlab paraméterek

A ${gitlab-access-token} placeholder helyére az itt létrehozott access token passwordjét kell megadni.

A ${backend-repo-útvonal}, ${frontend-repo-útvonal}, ${api-repo-útvonal}, ${bot-repo-útvonal} placeholderek helyére a megfelelő GitLab repository útvonalát kell megadni. Pl.: gbsolutions/${projekt-név}/backend

3.2.5 A jira paraméterek

A ${jira-project-tag} placeholder helyére a projekt Jira tag nevét kell megadni. (A projekt JIRA tag-je megegyezik a ticket ID prefixével: Pl.: Ha a ticket ID SEMI-1 akkor a JIRA tag: SEMI.)

A ${jira-access-token} placeholder helyére, kérjük el a Jira tokent a Semi csapattól:

Név Email cím Telefon Szerepkör
Katona Áron aron.katona@intuitech.studio +36203160057 Projekt Architekt
Kazsik Ádám adam.kazsik@intuitech.studio +36702900328 Szenior Fejlesztő
Surányi Ákos akos.suranyi@intuitech.studio +36203753887 Szenior Fejlesztő

A ${jira-username} placeholder helyére az alábbi email címet kell megadni: 

max.headroom@gbsolutions.io