Merge pull request #400 from waldekmastykarz/enh-lob-teamsextensions

Adds messaging extension on SPFx

solutions/LeadsLOBSolution/README.md

@@ -1,22 +1,51 @@
 # Leads Management System - LOB solution demo
 
-Demo solution demonstrating how to build a solution using SharePoint Framework and then surface it either as a SharePoint web part or as a Microsoft Teams tab:
+Demo solution demonstrating how to build a solution using SharePoint Framework and then surface it as a SharePoint web part, a Microsoft Teams tab, a personal app or a Teams messaging extension.
 
+> This solution was originally demonstrated in the SharePoint Conference 2018 keynote and also in the Ignite 2018. As part of the release of SharePoint Framework 1.7, it can be finally shared as a generic demo for the community.
+
+LOB solution exposed as a SharePoint web part:
 ![SharePoint web part](./assets/webpart-solution.png)
 
+LOB solution exposed as a Teams tab:
 ![Teams Tab](./assets/teams-tab-solution.png)
 
+LOB solution exposed as a personal Teams app:
 ![Personal Teams app](./assets/personal-app-solution.png)
 
-> This solution was originally demonstrated in the SharePoint Conference 2018 keynote and also in the Ignite 2018. As part of the release of SharePoint Framework 1.7, it can be finally shared as a generic demo for the community.
+LOB solution exposed as a Teams messaging extension:
+![Personal Teams app](./assets/messaging-extension.gif)
+
+## Prerequisites to use the messaging extension
+
+> **Important:** The ability to expose SharePoint Framework web parts as Teams messaging extensions is currently being developed and will be available publicly in the future versions of the SharePoint Framework.
+
+1. Register bot
+    1. Follow the instructions at [https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/create-a-bot-for-teams) to register a bot
+    1. For the messaging URL enter a mock URL, like `https://contoso.com/api/messaging`. You will update this URL later once you know the temporary URL created by ngrok
+    1. Note the Microsoft App ID and password. You will need them later to communicate with Teams
+1. Update bot data
+    1. In your code editor, navigate to the `bot/.env` file
+    1. Set the value of the `MICROSOFT_APP_ID` property to the Microsoft App ID you noted when registering the bot
+    1. Set the value of ohe `MICROSOFT_APP_PASSWORD` property to the Microsoft App password you noted when registering the bot
+    1. In your code editor, navigate to the `webpart/teams/manifest.json` file
+    1. In the `bots` and `composeExtensions` sections, update the value of the `botId` property to the Microsoft App ID you noted when registering the bot
+1. Start the web server with the bot locally
+    1. Install [ngrok](https://ngrok.com/) which is required to run the bot powering the messaging extension locally
+    1. Open terminal
+    1. Change the working directory to `bot`
+    1. Restore project dependencies by executing `npm install`
+    1. Start the local server with the bot by executing `gulp ngrok-serve`
+    1. Once ngrok started, note the hostname registered for the tunnel, eg. `b60b1863.ngrok.io`. The hostname is displayed in the terminal. You will need this to register the bot
+1. Update bot URL
+    1. In the web browser go to your bot registration page
+    1. Update the messaging URL to your ngrok domain, eg `https://b60b1863.ngrok.io/api/messaging`
 
 ## Installation
 
-1. From the **sharepoint/solution** folder, add the **leads.sppkg** file to the tenant app catalog in your SharePoint tenant.
-
-2. Navigate to the site where you want to install the solution - it's using tenant-scoped deployment, so web part is automatically exposed in the web part picker just by adding it to the app catalog.
-
-3. Move to Microsoft Teams and either upload the LeadsManagement.zip file from the Teams folder to app catalog of a specific Team or to the tenant level app catalog for Microsoft Teams.
+1. From the **webpart/sharepoint/solution** folder, add the **leads-lob.sppkg** file to the tenant app catalog in your SharePoint tenant.
+1. Navigate to the site where you want to install the solution - it's using tenant-scoped deployment, so web part is automatically exposed in the web part picker just by adding it to the app catalog.
+1. Move to Microsoft Teams and either upload the LeadsManagement.zip file from the Teams folder to app catalog of a specific Team or to the tenant level app catalog for Microsoft Teams.
 
 > Notice that you will need to enable side loading if you want to upload solution specifically to one team or to the Microsoft Team tenant app catalog. See following tutorial for additional details: [Building Microsoft Teams tab using SharePoint Framework - Tutorial](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/using-web-part-as-ms-teams-tab).
 
@@ -40,6 +69,8 @@ This solution is compatible with SharePoint Online. Teams capability only works
 
 Version|Date|Comments
 -------|----|--------
+1.3.0|May 18, 2020|Extended with Teams messaging extension
+1.2.0|May 11, 2020|Extended with a Teams task module
 1.1.0|May 1, 2020|Extended with a multi-tab personal Teams app configuration
 1.0.0|November 21, 2018|Updated to match v1.7 experience and tested in RTM
 

solutions/LeadsLOBSolution/bot/.deployment

@@ -0,0 +1,2 @@
+[config]
+command = deploy.cmd

solutions/LeadsLOBSolution/bot/.env

@@ -0,0 +1,29 @@
+# The domain name of where you host your application
+HOSTNAME=contoso.azurewebsites.net
+
+# App Id and App Password ofr the Bot Framework bot
+MICROSOFT_APP_ID=
+MICROSOFT_APP_PASSWORD=
+
+# Port for local debugging
+PORT=3007
+
+# Security token for the default outgoing webhook
+SECURITY_TOKEN=
+
+# ID of the Outlook Connector
+CONNECTOR_ID=
+
+# Application Insights instrumentation key
+APPINSIGHTS_INSTRUMENTATIONKEY=
+
+# NGROK configuration for development
+# NGROK authentication token (leave empty for anonymous)
+NGROK_AUTH=
+# NGROK sub domain. ex "myapp" or  (leave empty for random)
+NGROK_SUBDOMAIN=
+# NGROK region. (us, eu, au, ap - default is us)
+NGROK_REGION=
+
+# Debug settings, default logging "msteams"
+DEBUG=msteams

solutions/LeadsLOBSolution/bot/.gitignore

@@ -0,0 +1,11 @@
+# do not include the node modules in Git
+node_modules
+
+# do not include the package in Git
+package
+
+# do not include the Connectors Json Db file
+connectors.json
+
+# do not include dist files
+dist

solutions/LeadsLOBSolution/bot/.yo-rc.json

@@ -0,0 +1,11 @@
+{
+  "generator-teams": {
+    "promptValues": {
+      "developer": "Microsoft 365 PnP",
+      "unitTestsEnabled": false,
+      "useAzureAppInsights": false
+    },
+    "libraryName": "leadsBot",
+    "generator-version": "2.13.0"
+  }
+}

solutions/LeadsLOBSolution/bot/README-leadsBot.md

@@ -0,0 +1,20 @@
+# Leads Bot - `leadsBot`
+
+## How to register the bot in the Bot Framework portal
+
+In order to create a bot you need to first register it in the [Azure portal](https://portal.azure.com/).
+
+1. Choose to *Create a resource*, or alternatively go to an existing *resource group* and click *Add*
+2. Search for *Bot channels registration* and then click *Create*
+3. Give the bot a handle (ex: `leadsBot`), choose your subscription and resource group
+4. For the messaging endpoint, use this: `https://leadsbot.azurewebsites.net/api/messages`
+5. Choose to *Auto create Microsoft App ID and Password*
+6. Click *Create*
+7. Wait for Azure to finish its magic and when done choose to go to resource
+8. On the bot page choose *Channels* and choose to add Microsoft Teams as a channel
+9. Next, choose the *Settings* and click on *Manage* next to Microsoft App Id
+10. In the Bot app portal, generate a new app password and store it securely - you will need them for your `.env` file or add them as application settings for the hosting web site (see below)
+
+## How to configure the bot
+
+The App Id and App Secret, generated during the registration, for the bot are read from the `MICROSOFT_APP_ID` and `MICROSOFT_APP_PASSWORD` environment variables, specified in the `.env` file. These can be configured in the Azure Web App under *Application Settings > App Settings*.

solutions/LeadsLOBSolution/bot/README.md

@@ -0,0 +1,118 @@
+# Leads Bot - Microsoft Teams App
+
+Generate a Microsoft Teams application.
+
+TODO: Add your documentation here
+
+## Getting started with Microsoft Teams Apps development
+
+Head on over to [Microsoft Teams official documentation](https://developer.microsoft.com/en-us/microsoft-teams) to learn how to build Microsoft Teams Tabs or the [Microsoft Teams Yeoman generator Wiki](https://github.com/PnP/generator-teams/wiki) for details on how this solution is set up.
+
+## Project setup
+
+All required source code are located in the `./src` folder - split into two parts
+
+* `app` for the application
+* `manifest` for the Microsoft Teams app manifest
+
+For further details se the [Yo Teams wiki for the project structure](https://github.com/PnP/generator-teams/wiki/Project-Structure)
+
+## Building the app
+
+The application is built using the `build` Gulp task.
+
+``` bash
+npm i -g gulp gulp-cli
+gulp build
+```
+
+## Building the manifest
+
+To create the Microsoft Teams Apps manifest, run the `manifest` Gulp task. This will generate and validate the package and finally create the package (a zip file) in the `package` folder. The manifest will be validated against the schema and dynamically populated with values from the `.env` file.
+
+``` bash
+gulp manifest
+```
+
+## Configuration
+
+Configuration is stored in the `.env` file. 
+
+## Debug and test locally
+
+To debug and test the solution locally you use the `serve` Gulp task. This will first build the app and then start a local web server on port 3007, where you can test your Tabs, Bots or other extensions. Also this command will rebuild the App if you change any file in the `/src` directory.
+
+``` bash
+gulp serve
+```
+
+To debug the code you can append the argument `debug` to the `serve` command as follows. This allows you to step through your code using your preferred code editor.
+
+``` bash
+gulp serve --debug
+```
+
+To step through code in Visual Studio Code you need to add the following snippet in the `./.vscode/launch.json` file. Once done, you can easily attach to the node process after running the `gulp server --debug` command.
+
+``` json
+{
+    "type": "node",
+    "request": "attach",
+    "name": "Attach",
+    "port": 5858,
+    "sourceMaps": true,
+    "outFiles": [
+        "${workspaceRoot}/dist/**/*.js"
+    ],
+    "remoteRoot": "${workspaceRoot}/src/"
+},
+```
+
+### Using ngrok for local development and hosting
+
+In order to make development locally a great experience it is recommended to use [ngrok](https://ngrok.io), which allows you to publish the localhost on a public DNS, so that you can consume the bot and the other resources in Microsoft Teams. 
+
+To use ngrok, it is recommended to use the `gulp ngrok-serve` command, which will read your ngrok settings from the `.env` file and automatically create a correct manifest file and finally start a local development server using the ngrok settings.
+
+### Additional build options
+
+You can use the following flags for the `serve`, `ngrok-serve` and build commands:
+
+* `--no-linting` - skips the linting of Typescript during build to improve build times
+* `--debug` - builds in debug mode
+
+## Deploying to Azure using Git
+
+If you want to deploy to Azure using Git follow these steps.
+
+This will automatically deploy your files to Azure, download the npm pacakges, build the solution and start the web server using Express.
+
+1. Log into [the Azure Portal](https://portal.azure.com)
+2. Create a new *Resource Group* or use an existing one
+3. Create a new *Web App* with Windows App Service Plan and give it the name of your tab, the same you used when asked for URL in the Yeoman generator. In your case https://leadsbot.azurewebsites.net.
+4. Add the following keys in the *Configuration* -> *Application Settings*; Name = `WEBSITE_NODE_DEFAULT_VERSION`, Value = `8.10.0` and Name = `SCM_COMMAND_IDLE_TIMEOUT`,  Value = `1800`. Click Save.
+5. Go to *Deployment Center*
+6. Choose *Local Git* as source and *App Service build service* as the Build Provider 
+7. Click on *Deployment Credentials* and store the App Credentials securely
+8. In your tab folder initialize a Git repository using `git init`
+9. Build the solution using `gulp build` to make sure you don't have any errors
+10. Commit all your files using `git add -A && git commit -m "Initial commit"`
+11. Run the following command to set up the remote repository: `git remote add azure https://<username>@leadsbot.scm.azurewebsites.net:443/leadsbot.git`. You need to replace <username> with the username of the App Credentials you retrieved in _Deployment Credentials_. You can also copy the URL from *Options* in the Azure Web App.
+12. To push your code use to Azure use the following command: `git push azure master`, you will be asked for your credentials the first time, insert the Password for the App Credential. Note that you should update the Azure Web Site application setting before pushing the code as the settings are needed when building the application.
+13. Wait until the deployment is completed and navigate to https://leadsbot.azurewebsites.net/privacy.html to test that the web application is running
+14. Done
+15. Repeat step 11 for every commit you do and want to deploy
+
+> NOTE: The `.env` file is excluded from source control and will not be pushed to the web site so you need to ensure that all the settings present in the `.env` file are added as application settings to your Azure Web site (except the `PORT` variable which is used for local debugging).
+
+## Logging
+
+To enable logging for the solution you need to add `msteams` to the `DEBUG` environment variable. See the [debug package](https://www.npmjs.com/package/debug) for more information. By default this setting is turned on in the `.env` file.
+
+Example for Windows command line:
+
+``` bash
+SET DEBUG=msteams
+```
+
+If you are using Microsoft Azure to host your Microsoft Teams app, then you can add `DEBUG` as an Application Setting with the value of `msteams`.

solutions/LeadsLOBSolution/bot/gulp.config.js

@@ -0,0 +1,53 @@
+const config = {
+    injectSources: [
+        "./dist/web/scripts/**/*.js",
+        "./dist/web/styles/**/*.css"
+    ],
+    staticFiles: [
+        "./src/app/**/*.html",
+        "./src/app/**/*.ejs",
+        "./src/app/web/assets/**/*"
+    ],
+    htmlFiles: [
+        "./src/app/**/*.html", "./src/app/**/*.ejs"
+    ],
+    watches: [
+        "./src/app/**/*.*",
+        "!./src/app/**/*.scss",
+        "!./src/app/web/**/*.*",
+        "!./src/app/scripts/**/*.*",
+    ],
+    clientWatches: [
+        "./src/app/scripts/**/*.*",
+        "!./src/app/**/*.scss"
+    ],
+    manifests: [
+        "./src/manifest/**/*.*",
+        '!**/manifest.json'
+    ],
+    temp: [
+        "./temp"
+    ],
+    // Supported Schemas
+    SCHEMAS: [{
+            version: "1.3",
+            schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.3/MicrosoftTeams.schema.json"
+        },
+        {
+            version: "1.4",
+            schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.4/MicrosoftTeams.schema.json"
+        },
+        {
+            version: "devPreview",
+            schema: "https://raw.githubusercontent.com/OfficeDev/microsoft-teams-app-schema/preview/DevPreview/MicrosoftTeams.schema.json"
+        },
+        {
+            version: "1.5",
+            schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.5/MicrosoftTeams.schema.json"
+        }    
+    ],
+    // This is the name of the packaged manifest file
+    manifestFileName: "Leads Bot.zip"
+};
+
+module.exports = config;