Skip to content

Latest commit

 

History

History
 
 

nodejs

README.md

page_type description products languages extensions urlFragment
sample
This sample app demonstrates a bot that integrates Azure DevOps with Teams, notifying users of new work items and creating group chats. It supports adaptive cards and is built on .NET with full setup instructions provided.
office-teams
office
office-365
nodejs
javascript
contentType createdDate
samples
04/28/2022 00:15:15
officedev-microsoft-teams-samples-bot-release-management-nodejs

Bot to create a group chat and send a task notification using Azure service hook

This sample app integrates Azure DevOps with Teams using a bot to send notifications on work item creation. It leverages service hooks to create group chats and deliver work item details via adaptive cards, providing a streamlined way to keep teams informed in real time.

Included Features

  • Bots
  • Adaptive Cards

Interaction with app

Workitem card

Prerequisites

  • Microsoft Teams is installed and you have an account (not a guest account)
  • To test locally, NodeJS must be installed on your development machine (version 16.14.2 or higher).
  • dev tunnel or ngrok latest version or equivalent tunneling solution.
  • M365 developer account or access to a Teams account with the appropriate permissions to install an app.
  • Azure DevOps access to set up service hooks and add custom field in workitem.
  • Teams Toolkit for VS Code or TeamsFx CLI

Run the app (Using Teams Toolkit for Visual Studio Code)

The simplest way to run this sample in Teams is to use Teams Toolkit for Visual Studio Code.

  1. Ensure you have downloaded and installed Visual Studio Code
  2. Install the Teams Toolkit extension
  3. Select File > Open Folder in VS Code and choose this samples directory from the repo
  4. Using the extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps
  5. Select Debug > Start Debugging or F5 to run the app in a Teams web client.
  6. In the browser that launches, select the Add button to install the app to Teams.

If you do not have permission to upload custom apps (sideloading), Teams Toolkit will recommend creating and using a Microsoft 365 Developer Program account - a free program to get your own dev environment sandbox that includes Teams.

Setup

Note these instructions are for running the sample on your local machine, the tunnelling solution is required because the Teams service needs to call into the bot.

Setup NGROK

  1. Run ngrok - point to port 3978

    ngrok http 3978 --host-header="localhost:3978"

    Alternatively, you can also use the dev tunnels. Please follow Create and host a dev tunnel and host the tunnel with anonymous user access command as shown below:

    devtunnel host -p 3978 --allow-anonymous

  2. Once started you should see URL https://41ed-abcd-e125.ngrok-free.app. Copy it, this is your baseUrl that will used as endpoint for Azure bot and webhook.

Register Azure AD application

Register one Azure AD application in your tenant's directory: for the bot and tab app authentication.

  • Log in to the Azure portal from your subscription, and go to the "App registrations" blade here. Ensure that you use a tenant where admin consent for API permissions can be provided.

  • Click on "New registration", and create an Azure AD application.

  • Name: The name of your Teams app - if you are following the template for a default deployment, we recommend "App catalog lifecycle".

  • Supported account types: Select "Accounts in any organizational directory"

  • Leave the "Redirect URL" field blank.

  • Click on the "Register" button.

  • When the app is registered, you'll be taken to the app's "Overview" page. Copy the Application (client) ID; we will need it later. Verify that the "Supported account types" is set to Multiple organizations.

  • On the side rail in the Manage section, navigate to the "Certificates & secrets" section. In the Client secrets section, click on "+ New client secret". Add a description for the secret and select Expires as "Never". Click "Add".

  • Once the client secret is created, copy its Value, please take a note of the secret as it will be required later.

  • At this point you have 3 unique values:

    • Application (client) ID which will be later used during Azure bot creation
    • Client secret for the bot which will be later used during Azure bot creation
    • Directory (tenant) ID We recommend that you copy these values into a text file, using an application like Notepad. We will need these values later.

  • Under left menu, navigate to API Permissions, and make sure to add the following permissions of Microsoft Graph API > Application permissions:

    • Chat.Create
    • TeamsAppInstallation.ReadWriteForChat.All
    • AppCatalog.Read.All
    • User.Read.All
    • Teamwork.Migrate.All

Click on Add Permissions to commit your changes.

  • If you are logged in as the Global Administrator, click on the Grant admin consent for %tenant-name% button to grant admin consent else, inform your admin to do the same through the portal or follow the steps provided here to create a link and send it to your admin for consent.

  • Global Administrator can grant consent using following link: https://login.microsoftonline.com/common/adminconsent?client_id=<%appId%>

Setup for Bot

  • In Azure portal, create a Azure Bot resource.

  • Ensure that you've enabled the Teams Channel

  • If you are using Ngrok to test locally, you'll need Ngrok installed on your development machine. Make sure you've downloaded and installed Ngrok on your local machine. ngrok will tunnel requests from the Internet to your local computer and terminate the SSL connection from Teams.

Setup Azure DevOps service hook

  • Follow this document- Create Webhooks to service hook.

  • Make sure to select trigger as Work item created

  • Make sure to add URL as https://{baseUrl}/api/workItem. It will look somethihng as https://41ed-abcd-e125.ngrok-free.app/api/workItem. Here baseUrl is referred to URL we get in step 1. NOTE: If you are not getting incoming request from Azure DevOps make sure that service webhook is in Enabled state.

Setup custom work item type

Custom field

NOTE:Make sure you create a new task, click save and verify the stakeholderTeam value Execute Webhook

Setup for code

  1. Clone the repository

    git clone https://github.com/OfficeDev/Microsoft-Teams-Samples.git

  2. In the folder where repository is cloned navigate to samples/release-management/nodejs

  3. Install node modules

    Inside node js folder, open your local terminal and run the below command to install node modules. You can do the same in Visual studio code terminal by opening the project in Visual studio code

    npm install

  4. Update the .env configuration for the bot to use the MicrosoftAppId and MicrosoftAppPassword and MicrosoftAppTenantId (Note that the MicrosoftAppId is the AppId created in step 4 , the MicrosoftAppPassword is referred to as the "client secret" in previous steps and you can always create a new client secret anytime., MicrosoftAppTenantId is reffered to as Directory tenant Id in previous steps).

  5. Run your bot at the command line:

    npm start

Setup Manifest for Teams

  • This step is specific to Teams.
  • Edit the manifest.json contained in the /appManifest folder to and fill in MicrosoftAppId (that was created in step 1 and it is the same value of MicrosoftAppId as in .env file) everywhere you see the place holder string <<Microsoft-App-Id>> (depending on the scenario it may occur multiple times in the manifest.json)
  • Edit the manifest.json for validDomains with base Url domain. E.g. if you are using ngrok it would be https://1234.ngrok-free.app then your domain-name will be 1234.ngrok-free.app and if you are using dev tunnels then your domain will be like: 12345.devtunnels.ms.
  • Zip up the contents of the /appManifest folder to create a manifest.zip
  • Upload the manifest.zip to Teams (in the Apps view click "Upload an app to your org's app catalog")

Note: If you are facing any issue in your app, please uncomment this line and put your debugger for local debug.

Running the sample

Upload an app to your org's app catalog:

Upload AppOrg

Install App:

InstallApp

WorkItem Card UI:

InstallApp

View UI:

InstallApp

Interacting with the bot

  • Login into Azure DevOps and open the project where custom process was applied.
  • Create a new workitem -> Tasks, provide comma seprated email ids in StakeHolderTeam (NOTE: The email should belong to tenant where we register Application in step 4)
  • Save
  • Bot will create the group chat with members you added and send the Task details.

Deploy the bot to Azure

To learn more about deploying a bot to Azure, see Deploy your bot to Azure for a complete list of deployment instructions.

Further reading