Table of content

Foreword

Enable and Create Microsoft Teams

• Enable Microsoft Teams feature
• Create Teams
• Update Each Team

Import and publish LUIS App

• Import LUIS App
• Set application as public
• Train and Publish the App

Create and configure Bot

• Create a Bot
• Customize and Configure the Bot
• Add Microsoft Teams Channel

Create SharePoint Site and Lists

• Create a site collection
• Provision Lists
• Add preset data

Generate a self-signed certificate

• Generate certificate with PowerShell
• Get keyCredential
• Export the Certificate and Convert to Base64 String

Create App Registrations in AAD

• Get Tenant Id
• Create App Registration for the Bot Web App
• Create App Registration for the Metric Web App
• Create App Registration for the MS Graph Connector
• Add keyCredential to App Registrations

Deploy Azure Components with ARM Template

• GitHub Authorize
• Deploy Azure Components
• Handle Errors

Follow-up Steps

• Add Reply URL and Admin Consent Bot Web App
• Add Reply URL and Admin Consent Metric Web App
• Update Bot Messaging Endpoint
• Verify the Bot
• Authorize Planner API Connection
• Authorize Teams API Connection
• Authorize Microsoft Graph API Connection

Configure Teams App

• Start Conversation with The Bot
• Create Teams App Package and Side-load It
• Add Metric Input Tab
• Add Idea Board Tab

This document will guide you to deploy the solution to your environment.

First, an Azure AAD is required to register the app registrations. In this document, the Azure AAD will be called "Huddle AAD", and an account in Huddle AAD will be called Huddle work account.

• All app registrations should be created in the Huddle AAD.

• Bot/Luis/Microsoft App should be registered with a Huddle work account.

• SharePoint lists should be created on SharePoint associating with Huddle AAD.

An Azure Subscription is required to deploy the Azure components. We will use the ARM Template to deploy these Azure components automatically.

Please download files in /Files folder to your computer.

Please follow Enable Microsoft Teams features in your Office 365 organization.

Make sure the following options are turned on:

• Allow external apps in Microsoft Teams

• Allow sideloading of external apps

  

Excel & power shell

Global Team

For each team you created, please active the default planer and create 4 buckets:

1. Open https://www.office.com, sign in.

   

   Click Planner.

   Find the planner which has the same name as the team, then click it.

   

2. Create the following buckets:

   • New Idea
   • In Progress
   • Completed
   • Shareable

1. Open https://www.luis.ai/, then sign in with a Huddle work account.

2. Finish or skip the welcome page. Then go to the applications page:

   

3. Click Import App.

   

   • Click Choose File, and select /Files/LUISApp.json.
   • Click Import.

   ​

4. Copy aside the App Id. It will be used as the value of the Luis App Id parameter of the ARM Template.

1. Click Settings.

   

2. Check Set application as public.

   

3. Click Yes.

1. Click Train & Test at the left.

   

   Click Train Application.

2. Click Publish App at the left.

   

3. Click Publish to production slot.

1. Open https://dev.botframework.com in a browser, then sign in with the Huddle work account.

   

2. Click My bots, then click Create a bot.

   

3. Click Create

   

4. Select Register an existing bot built using Bot Builder SDK. Then click Ok.

1. Upload icon:

   

   Click Upload custom icon, then select /Files/HuddleBotIcon.png.

2. Input the fields:

   

   • Display name: Huddle Bot

   • Bot handle: HuddleBot**

   • Long description: This is the idea bot used to create and list ideas

     Note:

     • Bot handle should be unique, please add some suffix to avoid confliction.
     • Bot handle will be used as the value of Bot Id parameter of the ARM Template. Please copy it aside.

3. Leave Message endpoint empty for now. We will fill it later.

   

4. Configure Microsoft App:

   

   Click Create Microsoft App ID and password.

   

   Login in with the Huddle work account.

   An app will be created automatically:

   

   Copy aside the App ID. It will be used as the value of Microsoft App Id App setting. It will also be used in the Teams App manifest.json file as id.

   Then click Generate an app password to continue.

   

   Copy aside the password. It will be used as the value of **Microsoft App Password **parameter of the ARM Template.

   Then click OK.

   Click Finish and go back to Bot Framework.

   

5. Skip Analytics and Admin section.

6. Go to the end of the page:

   

   Check the I agree to ... checkbox, and click Register.

   Note: If you got an error of the Bot handle: Id is already in use. Please use another one.

7. Click OK.

   

1. Click the Microsoft Teams Icon under Add a channel section.

   

2. Click Done

   

3. Right-click the new added Microsoft Teams channel.

   

   Click Copy link address, and paste the URL to someplace. It will be used to add the Bot to Microsoft Teams later.

1. Open a web browser and go to SharePoint Administration Center.

   https://<YourTenant>-admin.sharepoint.com/_layouts/15/online/SiteCollections.aspx

2. Click New -> Private Site Collection.

   

3. Fill in the form:

   

   • In the **Title **field, enter site title.
   • In the Web Site Address field, enter hospital site URL.
   • Select a language: English
   • In the Template Selection section, select **Team Site **as site template.
   • Choose a Time Zone.
   • **Administrator **should be the alias of the individual you want to have full administrator rights on this site.
   • Leave Server Resource Quota **at 300. (This value can be adjusted later if needed)

4. Click OK.

5. Copy aside the URL of the site collection. It will be used as the value of Base SP Site Url parameter of the ARM Template.

1. Install SharePointPnPPowerShellOnline module, if you have not installed it.

   Please follow: https://msdn.microsoft.com/en-us/pnp_powershell/pnp-powershell-overview#installation

2. Open Power Shell, then execute the command below to connect to the site you just created:

   Connect-PnPOnline –Url https://<Tenant>.sharepoint.com/sites/<Site> –Credentials (Get-Credential)

   Note: Please replace <Tenant> and <Site>.

3. Login in with an admin account.

   

4. Navigate to /Files folder in PowerShell, then execute the following command:

   Apply-PnPProvisioningTemplate -Path PnPProvisioningTemplate.xml

Add some categories to the Categories list, for example:

• Safety/Quality
• Access
• Experience
• Finance
• People

Run PowerShell as administrator, then execute the commands below:

$cert = New-SelfSignedCertificate -Type Custom –KeyExportPolicy Exportable -KeySpec Signature -Subject "CN=Huddle App-only Cert" -NotAfter (Get-Date).AddYears(20) -CertStoreLocation "cert:\CurrentUser\My" -KeyLength 2048

Note: please keep the PowerShell window open until you finish the steps below.

Execute the commands below to get keyCredential:

Note: Feel free to change the file path at the end of the command.

$keyCredential = @{}
$keyCredential.customKeyIdentifier = [System.Convert]::ToBase64String($cert.GetCertHash())
$keyCredential.keyId = [System.Guid]::NewGuid().ToString()
$keyCredential.type = "AsymmetricX509Cert"
$keyCredential.usage = "Verify"
$keyCredential.value = [System.Convert]::ToBase64String($cert.GetRawCertData())
$keyCredential | ConvertTo-Json > c:\keyCredential.txt

The keyCredential is in the generated file, and will be used to create App Registrations in AAD.

The following commands will export the certificate and convert it to base64 string.

$password = Read-Host -Prompt "Enter password" -AsSecureString
$bytes = $cert.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Pfx, $password)
[System.Convert]::ToBase64String($bytes) | Out-File 'c:\cert-base64.txt'

You will be prompted to input a password to protect the certificate. Please copy aside the password. It will be used as the value of the Certificate Pfx Password parameter of the ARM Template

The base64 string of the certificate is in the generated text file, and will be used as the value of the Certificate Pfx Base64 parameter of the ARM Template.

Open the AAD in Azure Portal, then get the Directory ID.

The Directory ID will be used as the value of Tenant Id parameter of the ARM Template.

1. Create a new App Registration:

   • Name: Huddle Bot Web App

   • Application Type: Web app/API

   • Sign-on URL: https://huddle/bot-web-app

   • Permissions:

     API	Permission Type	Permissions
     Office 365 SharePoint Online (Microsoft.SharePoint)	Application	Read and write items and lists in all site collections
     Microsoft Graph	Delegated	Read and all groups Read all users’ full profiles

2. Copy aside the Application Id. It will be used as the values of Bot Client Id parameter of the ARM Template.

3. Create a new Key and copy aside its value. The key value will be used as the value of Bot Client Secret parameter of the ARM Template.

1. Create a new App Registration:

   • Name: Huddle Metric Web App

   • Application Type: Web app/API

   • Sign-on URL: https://huddle/metric-web-app

   • Permissions:

     API	Permission Type	Permissions
     Office 365 SharePoint Online (Microsoft.SharePoint)	Application	Read and write items and lists in all site collections
     Windows Azure Active Directory (Microsoft.Azure.ActiveDirectory)	Delegated	Read directory data Sign in and read user profile

2. Copy aside the Application Id. It will be used as the values of Metric Client Id parameter of the ARM Template.

3. Create a new Key and copy aside its value. The key value will be used as the value of Metric Client Secret parameter of the ARM Template.

1. Create a new App Registration:

   • Name: Huddle MS Graph Connector

   • Application Type: Web app/API

   • Sign-on URL: https://huddle/ms-graph-connector

   • Permissions:

     API	Permission Type	Permissions
     Microsoft Graph	Delegated	Read and write all groups Read all users’ full profiles

2. Copy aside the Application Id. It will be used as the values of Graph Client Id parameter of the ARM Template.

3. Create a new Key and copy aside its value. The key value will be used as the value of Graph Client Secret parameter of the ARM Template.

Follow the steps below to add keyCredential to App Registrations of the Bot Web App and Metric Web App

1. Open an App Registration

   

2. Click Manifest

   

3. Insert the keyCredential into the square brackets of the keyCredentials node.

4. Click Save.

1. Generate Token

   • Open https://github.com/settings/tokens in your web browser.

   • Sign into your GitHub account where you forked this repository.

   • Click Generate Token.

   • Enter a value in the Token description text box.

   • Select the following s (your selections should match the screenshot below):

     • repo (all) -> repo:status, repo_deployment, public_repo
     • admin:repo_hook -> read:repo_hook

     

   • Click Generate token.

   • Copy the token.

2. Add the GitHub Token to Azure in the Azure Resource Explorer

   • Open https://resources.azure.com/providers/Microsoft.Web/sourcecontrols/GitHub in your web browser.

   • Log in with your Azure account.

   • Selected the correct Azure subscription.

   • Select Read/Write mode.

   • Click Edit.

   • Paste the token into the token parameter.

     

   • Click PUT.

1. Fork this repository to your GitHub account.

2. Click the Deploy to Azure Button:

   

3. Fill in the values on the deployment page:

   

   You have collected most of the values in previous steps. For the rest parameters:

   • Global Team: the name of the global team.
   • Source Code Repository: use the URL of the repository you just created -https://github.com/<YourAccount>/Huddle
   • Source Code Branch: mater
   • Source code Manual Integration:
   • Check I agree to the terms and conditions stated above.

4. Click Purchase.

1. Get the URL of the Bot Web app, and change the schema to https, we will get a base URL.

   

   For example: https://huddle-bot.azurewebsites.net

2. Append / to the base URL, we will get the replay URL.

   For example: https://huddle-bot.azurewebsites.net/

   Add it the Bot App Registration.

   

3. Append /admin/consent to the base URL, we will get the admin consent URL.

   For example: https://huddle-bot.azurewebsites.net/admin/consent

   Open it in a browser, sign in with a Huddle admin account.

   

   Click Accept.

Follow the similar steps in the previous chapter to add the reply URL and admin consent.

1. Append /api/messages to the base URL of the Bot Web App, we will get the message endpoint URL.

   For example: https://huddle-bot-dev.azurewebsites.net/api/messages

2. Got to the Bot you created, then click SETTINGS.

   

3. Fill the Message endpoint

4. Click Save Changes at the bottom.

   Note: if you get error like below, please refresh the page and try it several times.

   

1. Navigate to the Bot you registered.

   

2. Click ->Test, input list ideas, then send.

   

3. If you get responses like above, the Bot is deployed successfully.

   Note: If the message could not be sent, please click retry for a few times.

   

1. Navigate to the resource group.

   

2. Click the planner API Connection.

   

3. Click This connection is not authenticated.

   

4. Click Authorize.

   Pick up or input the Huddle work account. The user account should be in every team.

   Sign in the account.

5. Click Save at the bottom.

Follow the similar steps in the previous chapter to authorize teams API Connection.

Due to some unknown reason, we can authorize the microsoft-graph API Connection as above.

Please use the steps below instead.

1. Click ListPlans Logic App

   

2. Click Edit

   

3. Click **Connections **to expand it, then click Invalid connection.

4. Pickup or input the Huddle account used to authorize planner and teams API Connections, then sign in.

Follow the step below to start 1:1 conversation with the Bot in Microsoft Teams

1. Find the URL of Microsoft Teams Channel of the Bot,

   

   Then open it in your browser:

   

2. Click Open Microsoft Teams.

Another way to start 1:1 talk is using the MicrosoftAppId of the Bot:

1. Open /Files/TeamsAppPackage/manifest.json with a text editor.

2. Replace the following 2 placeholders with the corresponding values you got in previous guides:

   • <MicrosoftAppId>: the App Id of the Microsoft App registered when creating the Bot

     

   • <MetricWebAppDomain>: the domain of the Metric Web App

     

3. Save the changes.

4. Zip the files in /Files/TeamsAppPackage folder.

   

   Name it HuddleTeamsApp.zip.

5. Right-click a team in Microsoft Teams, then click Manage team.

   

6. Click the Bots tab.

   

7. Then click Sideload a bot or tab.

8. Select the HuddleTeamsApp.zip.

1. Click a team.

   

2. Click +

   

3. Click Huddle App.

   

4. Click Accept.

   

5. Click Save.

1. Click a team.

   

2. Click +

   

3. Click Planner.

4. Sign in with the Huddle work account.

   

   Choose Use an existing plan, then select the plan which has the same name as the team.

5. Click Save.

   

6. Click the dropdown icon, then click Rename.

   

   Input: IdeaBoard

7. Click Save.