Updates from: 04/10/2021 04:09:34
Service Microsoft Docs article Related commit history on GitHub Change details
platform Create Apps For Teams Meetings https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/apps-in-teams-meetings/create-apps-for-teams-meetings.md
In-meeting dialog must not use task module. Task module is not invoked in a meet
#### Share to stage > [!NOTE]
-> This capability is avaialable only in insider dev preview
+> * This capability is currently available in developer preview only.
+> * To use this feature, the app must support an in-meeting sidepanel.
This capability gives developers the ability to share an app to the meeting stage. By enabling share to the meeting stage, meeting participants can collaborate in real-time.
-The required context is meetingStage in the app manifest. A pre-requisite for this is to have the meetingSidePanel context. This will enable the "Share" button in the sidepanel as depecited below
+The required context is `meetingStage` in the app manifest. A prerequisite for this is to have the `meetingSidePanel` context. This enables the **Share** button in the sidepanel as depecited in the following image:
+
+ ![share_to_stage_during_meeting experience](~/assets/images/apps-in-meetings/share_to_stage_during_meeting.png)
+
+The manifest change that is needed to enable this capability is as follows:
+
+```json
+
+"configurableTabs": [
+ {
+ "configurationUrl": "https://contoso.com/teamstab/configure",
+ "canUpdateConfiguration": true,
+ "scopes": [
+ "groupchat"
+ ],
+ "context":[
+
+ "meetingSidePanel",
+ "meetingStage"
+ ]
+ }
+ ]
+```
platform Debugging Local Testing Calling Meeting Bots https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/bots/calls-and-meetings/debugging-local-testing-calling-meeting-bots.md
Messaging bots use HTTP, but calls and online meeting bots use the lower-level T
## Configure ngrok.yml
-Go to [ngrok](https://ngrok.com) and sign up for a free account or log into your existing account. After you've signed in, go to the [dashboard](https://dashboard.ngrok.com) and get your authtoken.
+Go to [ngrok](https://ngrok.com) and sign up for a free account or log into your existing account. After you've signed in, go to the [dashboard](https://dashboard.ngrok.com) and get your auth token.
Create an ngrok configuration file `ngrok.yml` and add the following line. For more information on where the file can be located, see [ngrok](https://ngrok.com/docs#config):
Create an ngrok configuration file `ngrok.yml` and add the following line. For m
In [Calls and online meetings bots](./calls-meetings-bots-overview.md), we discussed call signaling on how bots detect and respond to new calls and events during a call. Call signaling events are sent through HTTP POST to the bot's calling endpoint.
-As with the bot's messaging API, in order for the Real-time Media Platform to talk to your bot, your bot must be reachable over the internet. Ngrok makes this simple. Add the following lines to your ngrok.yml:
+As with the bot's messaging API, for the Real-time Media Platform to talk to your bot, your bot must be reachable over the internet. Ngrok makes this simple. Add the following lines to your ngrok.yml:
```yaml tunnels:
tunnels:
Application-hosted media uses certificates and TCP tunnels. The following steps are required: 1. Ngrok's public TCP endpoints have fixed URLs. They are `0.tcp.ngrok.io`, `1.tcp.ngrok.io`, and so on. You must have a DNS CNAME entry for your service that points to these URLs. For example, let's say `0.bot.contoso.com` refers to `0.tcp.ngrok.io`, `1.bot.contoso.com` refers to `1.tcp.ngrok.io`, and so on.
-2. A SSL certificate is required for your URLs. To make it easy, use a SSL certificate issued to a wild card domain. In this case, it would be `*.bot.contoso.com`. This SSL certificate is validated by the media SDK, so it must match your bot's public URL. Note the thumbprint and install it in your machine certificates.
-3. Now, setup a TCP tunnel to forward the traffic to localhost. Write the following lines into your ngrok.yml:
+2. An SSL certificate is required for your URLs. To make it easy, use an SSL certificate issued to a wild card domain. In this case, it would be `*.bot.contoso.com`. This SSL certificate is validated by the media SDK, so it must match your bot's public URL. Note the thumbprint and install it in your machine certificates.
+3. Now, set up a TCP tunnel to forward the traffic to localhost. Write the following lines into your ngrok.yml:
```yaml media:
platform Send Proactive Messages https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/bots/how-to/conversations/send-proactive-messages.md
When using proactive messaging to send notifications you must ensure your users
* **What can users do in response.** Make it easy for your users to take actions based on your notifications. * **How can users opt out.** You must provide a path for users to opt out of additional notifications.
+### Scheduled messages
+
+When using proactive messaging to send scheduled messages to users, verify that your time zone is updated to their time zone. This ensures that the messages are delivered to the users at the relevant time. Schedule messages generally include:
+
+* **Why is the user receiving the message**: Make it easy for your users to understand the reason for which they are receiving the message.
+* **What can user do next**: Users can take the required action based on the message content.
+ ## Proactively install your app using Graph > [!Note]
platform Locally With An Ide https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/bots/how-to/debug/locally-with-an-ide.md
When testing your bot you need to take into consideration both the contexts you
The most comprehensive way to test your bot is by creating an app package and uploading it to Teams. This is the only method to test the full functionality available to your bot, across all scopes. There are two methods for uploading your app:
-* Use [App Studio](~/concepts/build-and-test/app-studio-overview.md)
+* Use [App Studio](~/concepts/build-and-test/app-studio-overview.md).
* [Create an app package](~/concepts/build-and-test/apps-package.md) manually, and then [upload your app](~/concepts/deploy-and-publish/apps-upload.md). > [!NOTE]
Use the https endpoint provided by ngrok in your app manifest.
## Test your bot without uploading to Teams
-Occasionally it may be necessary to test your bot without installing it as an app in Teams. We provide two methods for testing the bot. Testing your bot without installing it as an app can be useful to ensure your bot is available and responding, however it won't allow you to test the full breadth of Microsoft Teams functionality you may have added to your bot. If you need to fully test your bot, see [testing by uploading](#test-by-uploading-to-teams).
+Occasionally, it may be necessary to test your bot without installing it as an app in Teams. We provide two methods for testing the bot. Testing your bot without installing it as an app can be useful to ensure your bot is available and responding, however it won't allow you to test the full breadth of Microsoft Teams functionality you may have added to your bot. If you need to fully test your bot, see [testing by uploading](#test-by-uploading-to-teams).
### Use the Bot Emulator
platform App Fundamentals Overview https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/app-fundamentals-overview.md
Title: Teams platform development fundamentals
+ Title: App development fundamentals overview
description: Describe the foundational concepts of Teams platform development.
-# Teams platform development fundamentals
-Coming soon ...
+# Microsoft Teams app development fundamentals
+
+Microsoft Teams app fundamentals give the direction you need to create your custom Teams app. You can recognize the framework required to plan your Teams app. The document helps you to understand the user-app communication and figure out the kind of app surfaces you need to use or the APIs your app might require in the process. Get some inspiration to embrace interactivity that can deepen the app experience when you integrate with Teams.
+
+## Capabilities and entry points
+
+You can extend your Teams app in multiple ways. To be able to extend your app you must understand all the core capabilities and the entry points that work in a collaborative space. You can experiment with the extension points for building your apps. Important app project components help you to correctly configure your app page. Teams app can have [multiple capabilities](../concepts/capabilities-overview.md) and [entry points](../concepts/extensibility-points.md).
+
+## Understand your use cases
+
+You can recognize user issues and identify the answers to some common problems the users face. You can build your Teams app by finding the right combination to meet your user's needs. [Understand use cases](../concepts/design/understand-use-cases.md) to know how an end-user interacts with your app. You learn to understand the user and their problem. Some common questions answered are as follows:
+
+* Do you need authentication?
+* What problem is your app going to solve?
+* Who are the end-users of the app?
+* How should the onboarding experience be and what else the app can do?
+
+## Map your use cases to Teams app capabilities
+
+[Map your use cases](../concepts/design/map-use-cases.md) covers some common scenarios and how to choose your app's capabilities. Information to share your app and collaborate on items in an external system is provided. You can also learn how to initiate workflows and send notifications to users. Get additional tips on where to start, how to get social with users, conversational bots, and combining multiple features.
+
+## See also
+
+> [!div class="nextstepaction"]
+> [Integrate web apps with Teams](../samples/integrating-web-apps.md)
+
+> [!div class="nextstepaction"]
+> [Build your first Microsoft Teams app](../build-your-first-app/build-first-app-overview.md)
+
+## Next step
+
+> [!div class="nextstepaction"]
+> [Understand Teams app capabilities](capabilities-overview.md)
+
platform Capabilities Overview https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/capabilities-overview.md
Title: Understanding Teams app capabilities
+ Title: Understand app capabilities
description: Teams app capabilities explained Last updated 09/22/2020
-# Understanding Teams app capabilities
-*Capabilities* are the extension points for building apps on the Microsoft Teams platform.
+# Understand Microsoft Teams app capabilities
-There are multiple ways to extend Teams, so every app is unique: Some only have one capability (such as a webhook), while others have a few to give users options. For instance, your app could display data in a central location (tab) and present that same information through a conversational interface (bot).
+Extensibility or entry points are different ways in which an app can manifest itself to a user. For example, a user can interact with an app on a canvas tab to do an activity or might choose to do the same using a conversational bot. The various capabilities used to build your Teams app allow you to increase its usage scope.
+
+There are multiple ways to extend Teams, so every app is unique. Some only have one capability, such as a webhook, while others have more than one feature to give users various options. For example, your app can display data in a central location, that is, the **tab** and present that same information through a conversational interface, that is, the **bot**.
+
+## App capabilities
Your Teams app have one or all of the following core capabilities:
Your Teams app have one or all of the following core capabilities:
Your app can also take advantage of advanced capabilities, such as the [Microsoft Graph API for Teams](https://docs.microsoft.com/graph/teams-concept-overview).
-See the following illustration to get an idea which capabilities would provide the features you want in your app.
+The following illustration gives you an idea of which capabilities will provide the features you want in your app.
:::image type="content" source="../assets/images/capabilities-overview.png" alt-text="Mind map illustrating what Teams app capabilities are.":::
-## Doing what's best for your users
+## Always consider your user
+
+As you familiarize yourself with Teams app development, you understand its core fundamentals. You understand that there is more than one way to build certain features. In such scenarios, consider how you can provide a more native experience to your user.
+For example, you can collect user input in a form built as a tab in the app. You can also do this using a task module without switching views and disrupting user's flow of work. It is important to choose extension points that provide least deviation from a user's regular flow of work.
+
+## See also
-As you familiarize yourself with Teams app development, you'll begin to understand its subtleties. There's more than one way to build certain features (such as collecting user input). For example, you could embed a web-based form in a tab using an `<iframe>`. You could also do this in a tab using a task module, a Teams UI convention, for a more native experience your users may prefer.
+> [!div class="nextstepaction"]
+> [Build apps for Teams](../overview.md)
+## Next step
-Choosing the right capabilities and design comes down to first [understanding your audience's use cases](../concepts/design/understand-use-cases.md).
+> [!div class="nextstepaction"]
+> [Teams app entry points](../concepts/extensibility-points.md)
platform Map Use Cases https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/design/map-use-cases.md
Title: Map your use cases to app capabilities
+ Title: Map your use cases to Teams app capabilities
-description: Decide how to distribute your app
+description: Choose the correct app scope
-# Map your use cases to teams app capabilities
-If you haven't already, make sure you've [considered your use cases](~/concepts/design/map-use-cases.md) carefully. You should also have a good understanding of the [extensibility points and UI elements](~/concepts/extensibility-points.md) available for your app. Once you've figured out *what* your trying to solve, and *who* you're solving it for, it is time to start thinking about *how*.
+# Map your use cases to Teams app capabilities
-Below you'll find some common scenarios, and a selection of extensibility points and UI elements that work well with them. It isn't intended to be an exhaustive list, just to help you think through some of the possibilities available to you and the Teams platform.
+After you have identified *who* the user is and *what* problem you will solve, it is time to decide *how* to solve the problem. The *who*, *what*, and *how* completes the process of understanding and mapping your use cases to Teams app capabilities. You need to define the scope of the app based on the responses you have received from the user to your queries, and then decide which capability is best suited to build your app.
-## Create, share and collaborate on items in an external system
+> [!NOTE]
+> You must have a good understanding of the [entry points and UI elements](../../concepts/extensibility-points.md) available for your app. You must also make sure that you [considered your use cases](../../concepts/design/understand-use-cases.md) carefully.
-App for Microsoft Teams are a great way to interact with your data, and there are a variety of integration points to choose from.
+## Choose the correct scope for your app
-* Messaging extensions with search commands - Search external systems and share the results as an interactive card.
+While choosing the app scope, consider the following:
-* Messaging extensions with action commands - Collect information to insert into a data store or perform advanced searches.
+* An app can exist across scopes.
+* App capabilities, such as messaging extensions, follow users across scopes.
+* Users are often hesitant to add apps to Teams or channels.
+* Guest users can access content exposed in Teams or channels.
-* Tabs - Create embedded web experiences to view, work with, and share data.
+You can choose between personal scope and team or channel scope for your app depending on the following:
-* Connectors and webhooks - A simple way to push data into, and send data out of the Teams client.
+* For selecting personal scope, answer questions, such as:
+ * Are there one-on-one interactions with the app required for privacy or other reasons? For example, checking leave balance or other private information.
+ * Is there going to be collaboration among users who might not have any common Teams? For example, finding upcoming organization wide events in a company.
+ * Are there any personalized notifications or messages that will need to be sent to a user throughout the Teams app experience? For example, reminders for approvals or registrations.
-* Task modules - Interactive modal forms from wherever you need them to collect or display information.
+* For selecting team or channel scope, answer questions, such as:
+ * Is the information presented by the app, either in tab or through a bot, relevant and useful for most members in a Team? For example, Scrum app.
+ * Could the appΓÇÖs context change depending on the team in which it is added to? For example, PlannerΓÇÖs tasks are different in different teams.
+ * Is it possible that all members in a persona who need to collaborate are a part of a single team? For example, agents working on a ticket.
+
+The following scenarios will guide you in understanding the selection of entry points and UI elements that work well with Teams app capabilities:
+
+> [!NOTE]
+> It is not an exhaustive list, but will help you think through some of the possibilities available to you.
+
+## Create, share, and collaborate on items in an external system
+
+App for Microsoft Teams is a great way to interact with your data and there are a variety of integration points to choose from.
+
+* **Messaging extensions with search commands**: Search external systems and share the results as an interactive card.
+
+* **Messaging extensions with action commands**: Collect information to insert into a data store or perform advanced searches.
+
+* **Tabs**: Create embedded web experiences to view, work with and share data.
+
+* **Connectors and webhooks**: A simple way to push data and send data out of the Teams client.
+
+* **Task modules**: Interactive modal forms from wherever you need them to collect or display information.
## Initiate workflows and processes Sometimes you just need a quick way to start a process or workflow in an external system.
-* Messaging extensions action commands - Trigger from messages, allowing your users to quickly send the contents of a message to your web services.
+* **Messaging extensions action commands**: Trigger from messages, allowing your users to quickly send the contents of a message to your web services.
-* Task modules - Open them from a tab, a bot, or a messaging extension to collect information before initiating a workflow.
+* **Task modules**: Open them from a tab, a bot, or a messaging extension to collect information before initiating a workflow.
-* Conversational bots - Interact with your users through text and rich cards.
+* **Conversational bots**: Interact with your users through text and rich cards.
-* Outgoing webhooks - A good choice for a simple back-and-forth interaction when you don't need to build an entire conversational bot.
+* **Outgoing webhooks**: A good choice for a simple back-and-forth interaction when you don't need to build an entire conversational bot.
## Send notifications and alerts Send asynchronous notifications and alerts to your users in Teams. Use interactive cards to provide quick access to commonly used actions and links to additional information.
-* Conversational bots - Send proactive messages to groups, channels, or individual users.
+* **Conversational bots**: Send proactive messages to groups, channels, or individual users.
-* Connectors & incoming webhooks - Allow a channel to subscribe to receive messages. With a connector let users tailor the subscription with a configuration page.
+* **Connectors and incoming webhooks**: Permit a channel to subscribe to receive messages. A connector lets users tailor the subscription with a configuration page.
## Ask questions and get answers
-People have questions. You've probably got a lot of the answers stored away somewhere. Unfortunately, its often quite difficult to connect the two together.
+People have questions and you probably got a lot of the answers stored away somewhere. Unfortunately, it's often quite difficult to connect the two.
-* Conversational bots - Natural language processing, AI, machine learning, all the buzzwords. Use a bot powered by the intelligent cloud to connect your users to the answers they need.
+* **Conversational bots**: Natural language processing, AI, machine learning, and all the buzzwords. Use a bot powered by the intelligent cloud to connect your users to the answers they need.
-* Tabs - Embed your existing web portal in Teams, or create a Teams-specific version for added functionality.
+* **Tabs**: Embed your existing web portal in Teams or create a Teams-specific version for added functionality.
## Get social
-A collaboration platform is inherently a social platform. Let your creative side be free, and add some fun into your workplace.
-
-* All of them - Send jokes, give kudos, get some memes, toss out some emoji's or whatever else strikes your fancy.
+A collaboration platform is inherently a social platform. Let your creative side be free and add some fun into your workplace. All users must be able to send jokes, give kudos, get some memes, toss out some emojis, or anything else that strikes your fancy.
-## Anything you can do in a Single Page App (SPA)
+## Think in terms of a single-page app
-Tabs are embedded web pages. Pretty much anything you can do in a SPA, you can do in a tab in Teams. Just be sure to pay attention to scope - group and channel tabs are for shared experiences, personal tabs are for ... personal experiences. The team's list of stuff goes on the channel tab, the list of your stuff goes in the personal tab.
+Tabs are embedded web pages. Pretty much anything you can do in a SPA, you can do in a tab in Teams. Just be sure to pay attention to scope. Group and channel tabs are for shared experiences and personal tabs are for personal experiences. The team's list of stuff goes on the channel tab and the list of your stuff goes in the personal tab.
## Start small
-Not sure where to start? Feeling a bit overwhelmed with the awesome variety of options available to you? Don't fret, choose a core feature of your app and start there. Once you get a feel for the flow of information through the various contexts in Teams, it will be a lot simpler to picture a more complex interaction.
+Not sure where to start? Feeling a bit overwhelmed with the awesome variety of options available to you? You must choose a core feature of your app and start there. After you get a feel for the flow of information through the various contexts in Teams, it is a lot simpler to picture a more complex interaction.
+
+## Put it all together
+
+That being said, the best apps usually combine multiple features, creating an app that engages users in the right context with the right functionality at the right time. You must not force any functionality into a place it does not belong. Just because you have a good one-to-one conversational bot does not mean you add it to any team. Different extensibility points are good for different things, play to their strengths for creating a successful app.
+
+## See also
-## Putting it all together
+> [!div class="nextstepaction"]
+> [Build apps for Microsoft Teams](../../overview.md)
+
-That being said, the best apps usually combine multiple features, creating an app that engages users in the right context with the right functionality at the right time. Don't try to force functionality into a place it doesn't belong - just because you've got a good one-to-one conversational bot doesn't mean you should just add it to a team. Different extensibility points are good for different things; play to their strengths and your app will shine.
platform Understand Use Cases https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/design/understand-use-cases.md
description: Understand your use cases
+ # Understand your use cases
-The Microsoft Teams platform offers a large variety of [extensibility points and UI elements](~/concepts/extensibility-points.md) your app can take advantage of. If you don't already have a good understanding of what is possible on the Teams platform, you should read that article first.
+The Microsoft Teams platform offers a large variety of [entry points and UI elements](../../concepts/extensibility-points.md) your app can take advantage of.
+> [!NOTE]
+> Before you start building your use cases, you must have a good understanding of Teams capabilities and what is possible on the Teams platform using them.
+
+Each method of interacting with your users has its strengths and weaknesses. Building an awesome Teams app is all about finding the right combination to meet your user's needs. If you are going to meet those needs, you first need to understand them.
+
+## Understand the problem
+
+Every good app has a core problem or a need it is trying to solve. Before you start building an app, you need to articulate what that problem is. At its heart, Teams is a collaboration platform, so apps that bridge gaps in achieving effective collaboration are a great fit. It is also a social platform, is natively cross-platform, sits at the heart of Office 365, and offers a personal canvas for you to create apps. In this social platform, there is a wide variety of needs that can be solved with a Teams app. You can solve wide variety of problems, provided you understand which one you are trying to solve. Before you start building an app, ask relevant questions, such as:
+
+* What are the pros and cons of the current state system used by your users?
+* What are the pain points your users face as of today that you wish to address?
+* What features or capabilities your users like and love in their current way of doing the process?
-Each method of interacting with your users has it's own strengths and weaknesses. Building an awesome Teams app is all about finding the right combination to meet your user's needs. If you're going to meet those needs, you first need to understand them.
+## Understand your user
-## What problem are you trying to solve?
+Understand who your user is and you can identify the right distribution model but more importantly, it helps you to identify how users use Teams. Ask relevant questions, such as:
-Every good app has a core problem (or need) it is trying to solve - before you start building you need to articulate what that problem is. At it's heart, Teams is a collaboration platform, so apps looking to solve collaboration problems are a great fit. It's also a social platform, is natively cross-platform, sits at the heart of Office 365, and offers a personal canvas for you to create apps on. There is an incredibly wide variety of needs that can be solved with a Teams app, just be sure you understand which one you're trying to solve.
+* Are the users primarily front-line workers on mobile clients?
+* Do you expect a lot of guest users to need access to your app?
+* Do they use teams and channels or primarily group chats?
+* How technically sophisticated are your primary users?
+* Do you need a thorough onboarding experience or a few pointers might do?
-## Who are you solving it for?
+Sometimes the answer is, *We want to solve this problem for all Teams users everywhere.* If that is the case for you, spend some time understanding [what it takes to get published to AppSource](~/concepts/deploy-and-publish/appsource/prepare/submission-checklist.md).
-Sometimes this can be obvious - "My team's monitoring system needs to send alerts somewhere, we need to be able to discuss them really quickly, and none of us want to check our email." Sometimes your target audience can grow over time - "Our sister team is really jealous of our alerting system, and now they want in on the action." Understanding who your users are will help you identify the right distribution model, but more importantly will help you identify *how they use Teams*. Are they primarily front-line workers on mobile clients? Do you expect a lot of guest users to need access to your app? Do they use teams and channels, or primarily group chats? How technically sophisticated are they? Will you need a thorough on-boarding experience, or will a few pointers do?
+## Understand the limitations of the app
-Sometimes the answer is "We want to solve this problem for all Team's users everywhere." If that's the case for you you'll want to spend some time understanding [what it takes to get published to AppSource](~/concepts/deploy-and-publish/appsource/prepare/submission-checklist.md).
+Knowing the limitations of the apps in terms of data accessibility and data residency requirement will help you design better apps. This is important, as having information on who owns the data and availability of APIs impacts the solution architecture. Again, ask relevant questions, such as:
-## Do you need authentication?
+* What are the challenges with back end integration of the current app?
+* Who owns the back end data? In-house or third-party.
+* Are there firewalls that impact the functioning of the app?
+* Are there APIs to access the data you need for functioning of your app?
-You should identify early on if you're going to need to protect the services you're exposing, and at what level. Remember the web services you'll be exposing in your Teams app are publicly available over the internet, so if you need to secure them start thinking about how now.
+## Provide authentication
-## Should the entire app be in Teams?
+You must identify early on if you need to protect the services you are exposing and at what level. Remember, the web services exposed in your Teams app are publicly available over the internet. So, if you need to secure them start thinking about it now. If you need a solution that requires you to provide guest access for users outside the tenant, access restrictions and permissions need to be placed to protect confidential information. You will need to design apps considering the limitations that come with guest user access. Therefore, ask questions, such as:
-Whether you're building something entirely new, or bringing an existing solution into Teams, it is important to decide if the entire app is going to be inside the Teams client, or if it makes sense to only bring in a portion of the experience. With a combination of tabs, messaging extensions, task modules, interactive cards, and conversational bots you can build complex apps completely inside of Teams. However, that doesn't always make sense. Remember who your users are, and the problem you're trying to solve. Do they already have a system for solving most of the problem, and you just need to extend a sub-set of the functionality into Teams? Typically if you're only going to bring in a portion of your solution you should focus on sharing, collaboration, and initiating and monitoring workflows.
+* Will the users access different views of data based on their roles?
+* Is there PII involved?
+* Will the interactions also be based on the user roles?
+* Will external users access the app?
-## What will the onboarding experience be like?
+## Decide what goes in Teams
-Your onboarding experience can be the difference between success or failure for your app. For each capability of your app, and for each context that capability can be installed in, you should have a plan for how you're going to introduce yourself. How you introduce your conversational bot when it is installed in a channel with a thousand people will probably be different than when it is installed in a one-to-one chat. What happens when a user first configures your tab in a channel? If you're sharing cards with a messaging extension, does it make sense to add a small link to a "learn more" page to help introduce users to what else your app can do?
+Whether you are building something new or bringing an existing solution into Teams, it is important to decide if the entire app is going to be inside the Teams client. Check if it makes sense to only bring in a portion of the experience. With a combination of tabs, messaging extensions, task modules, Adaptive Cards, and conversational bots you can build complex apps completely in Teams.
+Remember who your users are and the problem you are trying to solve. Do they already have a system for solving most of the problem or you just need to extend a sub-set of the functionality into Teams? Typically, if you are going to bring in a portion of your solution, you must focus on sharing, collaborating, initiating, and monitoring workflows.
-Knowing who your users are will help you craft the right experience. Do you expect most people to already have some context of what your app is for, or to have already used your services in another context? Or are they coming to your app with no prior knowledge? Craft your onboarding experience with your key users in mind.
+## Plan the onboarding experience
-Remember too that users can discover your app in a variety of ways - they might be the ones installing it, or they might be introduced to your app when another team member uses it to share content. If you want your app to spread, you should look for ways to introduce yourself to everyone.
+Your onboarding experience can be the difference between success or failure for your app. For each capability of your app and each context that capability can be installed in, you must have a plan for how you are going to introduce yourself. How you introduce your conversational bot when it is installed in a channel with a thousand people, is different when it is installed in a one-to-one chat. What happens when a user first configures your tab in a channel? If you are sharing cards with a messaging extension, does it make sense to add a small link to a **learn more** page to help introduce users to what else your app can do?
+
+Knowing who your users are helps you to craft the right experience. Do you expect most people to already have some context of what your app is for, or to have already used your services in another context? Are they coming to your app with no prior knowledge? Craft your onboarding experience with your key users in mind.
+
+Remember, users can discover your app in a variety of ways. They might be the ones installing it or they might be introduced to your app when another user uses it to share content. If you want more users to use your app, you must look for ways to introduce yourself to everyone.
Above all else, remember that nobody likes spam. Blasting away with personal and channel messages is a good way to get un-installed quickly!
-## Next steps
+## Plan for the future
+
+Identify which new features the user will prefer to have in the current solution. If you have a roadmap for new features to add to the app, the design and architecture will be impacted.
+
+## See also
+
+> [!div class="nextstepaction"]
+> [Choose how to distribute your app](../deploy-and-publish/overview.md)
-* [Map your use cases to functionality](~/concepts/design/map-use-cases.md)
-* [Choose how to distribute your app](../deploy-and-publish/overview.md)
+> [!div class="nextstepaction"]
+> [Design effective tabs](../../tabs/design/tabs.md)
-## Learn More
+> [!div class="nextstepaction"]
+> [Design amazing bots](../../bots/design/bots.md)
-* [Design effective tabs](~/tabs/design/tabs.md)
-* [Create amazing bots](~/bots/design/bots.md)
+## Next step
+> [!div class="nextstepaction"]
+> [Map your use cases](../../concepts/design/map-use-cases.md)
platform Extensibility Points https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/concepts/extensibility-points.md
description: Describes where people can discover and use your app in Teams. Previously updated : 09/22/2020
-# Entry points for Teams apps
-The Teams platform provides a flexible set of entry points where people can discover and use your app. Your app can be as simple as embedding existing web content in a tab or a multi-faceted app that users interact with across several contexts.
+# Entry points for Teams apps
-The most successful apps feel native to Teams, so it's important to carefully plan your app's entry points.
+The Teams platform provides a flexible set of entry points, such as team, channel, and chat where people can discover and use your app. Your app can be as simple as embedding existing web content in a tab or a multi-faceted app that users interact with across several contexts.
+The most successful apps are native to Teams, so choose your app's entry points carefully.
-## Teams, channels, and chats
+## Shared app experiences
-Teams, channels, and chats are collaboration spaces. Apps in these contexts are available to everyone in that space and typically focus on additional workflows or unlocking new social interactions.
+Team, channel, and chat are collaboration spaces. Apps in these contexts are available to everyone in that space. Collaboration spaces typically focus on additional workflows or unlocking new social interactions.
-Here's how Teams app capabilities are commonly used in collaborative contexts:
+The following list shows how Teams app capabilities are commonly used in collaborative contexts:
-* [**Tabs**](~/tabs/what-are-tabs.md) provide a full-screen embedded web experience configured for the team, channel, or group chat. All members interact with the same web-based content, so a stateless single page app experience is typical.
+* [**Tabs**](~/tabs/what-are-tabs.md) provide a full-screen embedded web experience configured for the team, channel, or group chat. All members interact with the same web-based content, so a stateless single-page app experience is typical.
-* [**Messaging extensions**](~/messaging-extensions/what-are-messaging-extensions.md) are shortcuts for inserting external content into a conversation or taking action on messages without leaving Teams. Link unfurling provides rich content when sharing content from a common URL.
+* [**Messaging extensions**](~/messaging-extensions/what-are-messaging-extensions.md) are shortcuts for inserting external content into a conversation or taking action on messages without leaving Teams. [Link unfurling](~/messaging-extensions/how-to/link-unfurling.md) provides rich content when sharing content from a common URL.
-* [**Bots**](~/bots/what-are-bots.md) interact with members of the conversation through chat and responding to events (like adding a new member or renaming a channel). Conversations with a bot in these contexts are visible to all members of the team, channel, or group, so bot conversations should be relevant to everyone.
+* [**Bots**](~/bots/what-are-bots.md) interact with members of the conversation through chat and responding to events, such as adding a new member or renaming a channel.
+ > [!NOTE]
+ > Conversations with a bot in these contexts are visible to all members of the team, channel, or group, so bot conversations must be relevant to everyone.
* [**Webhooks and connectors**](~/webhooks-and-connectors/what-are-webhooks-and-connectors.md) allow an external service to post messages into a conversation and users to send messages to a service. * [**Microsoft Graph REST API**](https://docs.microsoft.com/graph/teams-concept-overview) for getting data about teams, channels, and group chats to help automate and manage Teams processes.
-## Personal apps
+## Personal app experiences
-[Personal apps](~/concepts/design/personal-apps.md) focus on interactions with a single user. The experience in this context is unique to each user.
+[Personal apps](../concepts/design/personal-apps.md) focus on interactions with a single user. The experience in this context is unique to each user.
-Here's how Teams capabilities are commonly used in personal contexts:
+The following list shows how Teams capabilities are commonly used in personal contexts:
* [**Bots**](~/bots/what-are-bots.md) have one-on-one conversations with a user. Bots that require multi-turn conversations or provide notifications relevant only to a specific user are best suited in personal apps.
-* [**Tabs**](~/tabs/what-are-tabs.md) provide a full-screen embedded web experience that's meaningful to the user looking at it.
+* [**Tabs**](~/tabs/what-are-tabs.md) provide a full-screen embedded web experience that is meaningful to the user looking at it.
-## Examples
+## See also
+
+> [!div class="nextstepaction"]
+> [Teams app design guidelines](../concepts/design/design-teams-app-overview.md)
-The Teams app design guidelines provide detailed visuals showing you where people can find and use Teams apps.
+## Next step
> [!div class="nextstepaction"]
-> [See the Teams app design guidelines](../concepts/design/design-teams-app-overview.md)
+> [Understand use cases](../concepts/design/understand-use-cases.md)
platform Test Resource Specific Consent https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/graph-api/rsc/test-resource-specific-consent.md
Resource-specific consent (RSC) is a Microsoft Teams and Graph API integration t
> To test the RSC permissions, your Teams app manifest file must include a **webApplicationInfo** key populated with the following fields: > > - **id**: Your Azure AD app ID, see [Register your app in the Azure AD portal](resource-specific-consent.md#register-your-app-with-microsoft-identity-platform-via-the-azure-ad-portal).
-> - **resource**: Any string, see the note in [Update your Teams app manifest](resource-specific-consent.md#update-your-teams-app-manifest)
+> - **resource**: Any string, see the note in [Update your Teams app manifest](resource-specific-consent.md#update-your-teams-app-manifest).
> - **application permissions**: RSC permissions for your app, see [Resource-specific Permissions](resource-specific-consent.md#resource-specific-permissions). ```json
Resource-specific consent (RSC) is a Microsoft Teams and Graph API integration t
To check whether the RSC permissions are being honored by the API request payload, you need to copy the [RSC JSON test code](test-rsc-json-file.md) into your local environment and update the following values:
-* `azureADAppId`: Your app's Azure AD app ID
-* `azureADAppSecret`: Your Azure AD app secret (password)
-* `token_scope`: The scope is required to get a token - set the value to https://graph.microsoft.com/.default
+* `azureADAppId`: Your app's Azure AD app ID.
+* `azureADAppSecret`: Your Azure AD app password.
+* `token_scope`: The scope is required to get a token. set the value to https://graph.microsoft.com/.default.
* `teamGroupId`: You can get the team group id from the Teams client as follows:
- > [!div class="checklist"]
- >
- > * In the Teams client, select **Teams** from the far left navigation bar .
- > * Select the team where the app is installed from the dropdown menu.
- > * Select the **More options** icon (&#8943;)
- > * Select **Get link to team**
- > * Copy and save the **groupId** value from the string.
+ 1. In the Teams client, select **Teams** from the far left navigation bar.
+ 2. Select the team where the app is installed from the dropdown menu.
+ 3. Select the **More options** icon (&#8943;).
+ 4. Select **Get link to team**.
+ 5. Copy and save the **groupId** value from the string.
### Use Postman
platform Developer Tools https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tabs/how-to/developer-tools.md
When Teams is running in a browser, it is easy to access the browser's DevTools:
1. Add breakpoints to your JavaScript code and perform interactive debugging. > [!NOTE]
-> The feature is only available in desktop and Android clients after **Developer Preview** has been enabled. For more information, see [How do I enable developer preview](~/resources/dev-preview/developer-preview-intro.md).
+> The feature is only available for desktop and Android clients after the **Developer Preview** has been enabled. For more information, see [How do I enable developer preview](~/resources/dev-preview/developer-preview-intro.md).
## Access DevTools in the Desktop
-While the web version and the desktop version of Teams are almost exactly the same, there are some differences with respect to authentication. Sometimes the only way to figure out what is going on is to use the DevTools. To use DevTools in the desktop client, you must:
+While the web version and the desktop version of Teams are almost the same, there are some differences concerning authentication. Sometimes the only way to figure out what is going on is to use the DevTools. To use DevTools in the desktop client, you must:
1. Ensure you have enabled [developer preview](~/resources/dev-preview/developer-preview-intro.md). 1. Open up a tab so you have something to inspect with the DevTools. 1. Open the DevTools in one of the following ways: * **Windows**: Select the Teams icon in the desktop tray.
- * **MacOS**: Select the Teams icon in the Dock.
+ * **macOS**: Select the Teams icon in the Dock.
The following image shows DevTools inspecting an element in a tab configuration dialog:
While the web version and the desktop version of Teams are almost exactly the sa
You can also enable the DevTools from the Teams Android client. To enable DevTools, you must: 1. Enable the [developer preview](~/resources/dev-preview/developer-preview-intro.md).
-1. Connect your device to your desktop computer, and setup your Android device for [remote debugging](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/).
+1. Connect your device to your desktop computer, and set up your Android device for [remote debugging](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/).
1. In your Chrome browser, open `chrome://inspect/#devices`. 1. Select **inspect** under the tab you wish to debug, as in the following image:
platform Get Started Yeoman https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/get-started-yeoman.md
# Create your first Microsoft Teams app using the Yeoman generator
->[!Note]
->This tutorial comes from the [Yeoman generator for Teams wiki](https://github.com/OfficeDev/generator-teams/wiki/Build-Your-First-Microsoft-Teams-App).
+> [!Note]
+> This tutorial comes from the [Yeoman generator for Teams wiki](https://github.com/OfficeDev/generator-teams/wiki/Build-Your-First-Microsoft-Teams-App).
-In this tutorial we will walk through creating your very first Microsoft Teams app using the Microsoft Teams Yeoman generator. It assumes that you have a Teams account that allows [app sideloading](~/concepts/build-and-test/prepare-your-o365-tenant.md).
+In this tutorial, we will walk through creating your very first Microsoft Teams app using the Microsoft Teams Yeoman generator. It also walks you through the process of upgrading your Teams using the Yeoman generator. The prerequisite to start with this tutorial is that you have a Teams account that allows [app sideloading](~/concepts/build-and-test/prepare-your-o365-tenant.md).
![yeoman generator git](~/assets/yeoman-demo.gif)
You need to have Node.js installed on your machine. You should use the latest [L
### Install a code editor
-You also need a code editor, feel free to use whatever text editor you prefer. However most of this documentation and screenshots refer to using [Visual Studio Code](https://code.visualstudio.com).
+You need a code editor. Most of this documentation and images refer to using [Visual Studio Code](https://code.visualstudio.com). However, feel free to use whatever text editor you prefer.
### Install Yeoman and Gulp CLI
-To be able to scaffold projects using the Teams generator you need to install the Yeoman tool as well as the Gulp CLI task manager.
+To scaffold projects using the generator, you must install the Yeoman tool and Gulp CLI task manager.
Open up a command prompt and type the following:
Install the Teams Yeoman generator with the following command:
npm install generator-teams --global ```
-To install preview versions of the generator, run this command:
+Install the preview version of the generator with the following command:
```bash npm install generator-teams@preview --global
npm install generator-teams@preview --global
## Generate your project
-Open up a command prompt and create a new directory where you want to create your project and in that directory run the command `yo teams`.
+This section walks you through the steps for generating your project.
-This starts the generator, which prompts you with a set of questions.
+**To generate your project**
-![yo teams](~/assets/yeoman-images/teams-first-app-1.png)
+1. Open up a command prompt and create a new directory where you want to create your project, and in that directory run the command `yo teams`. The generator starts.
+1. Respond to the set of questions prompted by the generator.
-The first question is about your project name, you can leave it as is by pressing enter. Next question asks you if you want to create a new directory or use the current one. As we already are in the directory we want, we just press enter.
+ ![yo teams](~/assets/yeoman-images/teams-first-app-1.png)
-The following step asks for a title of your project, this title will be used in the manifest and description of your app. And then you will be asked for a company name, which also will be used in the manifest.
+ 1. The first question is about your project name, you can leave it as is by pressing enter.
+ 1. Next question asks you if you want to create a new directory or use the current one. As you are already in the directory you want, just press enter.
+ 1. In the next question, type the title of your project. This title will be used in the manifest and description of your app.
+ 1. Next, you will be asked for a company name, which also will be used in the manifest.
+ 1. The fifth question asks you about what version of the manifest you want to use. For this tutorial select `v1.5`, which is the current general available schema.
+ 1. Next, the generator will ask you for what items you want to add to your project. You can select a single one or any combination of items. For this tutorials, just select *a Tab*.
-The fifth question asks you about what version of the manifest you want to use. For this tutorial select `v1.5`, which is the current general available schema.
+ ![item selection](~/assets/yeoman-images/teams-first-app-2.png)
-After this the generator will ask you for what items you want to add to your project. You can select a single one or any combination of items. For now, just select *a Tab*.
+1. Respond to the next set of follow-up questions that appear based on the items you selected in step 2.
+1. Enter a URL of where you will host your solution.
-![item selection](~/assets/yeoman-images/teams-first-app-2.png)
+ > [!NOTE]
+ > The URL can be any URL, but by default the generator suggests an Azure web site URL.
-Based on what items you select, you will be asked a set of follow-up questions.
+1. In the next question, confirm if you want to include unit-testing for your solution. The default response is *yes*. If you choose to include unit-testing, the generated project will have a unit testing framework and some default unit tests for the different items being scaffolded.
+ > [!NOTE]
+ > * For this tutorial choose not to include a test framework.
+ > * The generator has a lot of built-in advanced features that you can opt-in or opt-out of.
-Now you need to enter a URL of where you will host your solution. This can be any URL, but by default the generator suggests an Azure Web Sites URL.
+1. In order to make signing-in easy for you, you will also be asked if you want to use Azure Application Insights for signing-in. If you choose *Yes*, you will need to provide an Azure Application Insights key.
-The generator has a lot of built-in advanced features that you can opt-in or opt-out of. Following the URL question you will be asked if you want to include unit-testing for your solution, default is yes. If you choose this the generated project will have a unit testing framework and some default unit tests for the different items being scaffolded. For this tutorial choose not to include a test framework.
+ > [!NOTE]
+ > For this tutorial opt-out of using Application Insights.
-In order to make logging easy for you, you will also be asked if you want to use Azure Application Insights for logging. If you choose Yes, you will need to provide a Azure Application Insights key. For this tutorial opt-out of using Application Insights.
-
-The next set of questions will be based on your selection of items previously. For a tab you only need to provide a name and optionally choose if you want to be able to use this app as a SharePoint Online web part. Once you have provided this name the generator will generate the project and install all dependencies. This will take a minute or two.
+The next set of questions will be based on the previously selected items. For a tab you only need to provide a name and optionally choose if you want to be able to use this app as a SharePoint Online web part. After you provide the name the generator will generate the project and install all dependencies. This will take a minute or two.
## Add some code to your tab
-Once the generator is done you can open up the solution in your favorite code editor. Take a minute or two and familiarize yourself with how the code is organized - you can read more about that in the [Project Structure](https://github.com/OfficeDev/generator-teams/wiki/Project-Structure) documentation.
+After the generator is done you can open up the solution in your favorite code editor. Take a minute or two and familiarize yourself with how the code is organized. For more information, see [Project Structure](https://github.com/OfficeDev/generator-teams/wiki/Project-Structure) documentation.
-Your Tab will be located in the `./src/app/scripts/myFirstAppTab/MyFirstAppTab.tsx` file. This is the TypeScript React based class for your Tab. Locate the `render()` method and add a line of code inside the `<PanelBody>` control so it looks like this:
+Your tab is in the `./src/app/scripts/myFirstAppTab/MyFirstAppTab.tsx` file. This is the TypeScript React-based class for your tab. Locate the `render()` method and add a line of code inside the `<PanelBody>` control so it looks like this:
``` TypeScript <PanelBody>
Choose your tab and follow the instructions to add it. Notice that you have a cu
![running tab in teams](~/assets/yeoman-images/teams-first-app-6.png)
-**Congrats! You built and deployed your first Microsoft Teams app**
+## Upgrade Microsoft Teams
+
+You can also upgrade your current Microsoft Teams version to the latest version using the Microsoft Teams Yeoman generator.
+
+**To upgrade Microsoft Teams**
+
+1. Get current version of Teams with the following command:
+
+ ```PowerShell
+ yo teams --version
+ ```
+2. Use the following command to select update your generator:
+
+ ```PowerShell
+ yo
+ ```
+3. Use the arrow keys to choose **Update your Generators**.
+
+ ![image of YoSelectUpdatGen](~/assets/images/Update-Teams/YoSelectUpdateGen.png)
+
+4. Select the generator you want from the list of generators.
+ > [!NOTE]
+ > Use the space bar to select or clear a selected Teams version from the available options.
+
+ ![image of UseSpaceToSelectGenerators](~/assets/images/Update-Teams/UseSpaceToSelectGenerators.png)
+
+
+ > [!NOTE]
+ > It takes few seconds to minutes for Teams installation to complete.
+
+5. After the installation is complete, use the following command to check the installed version:
+
+ ```PowerShell
+ yo teams --version
+ ```
+
+**Congrats! You built and deployed your first Microsoft Teams app. You also upgraded Microsoft Teams.**
platform Upgrade Using Yeoman https://github.com/MicrosoftDocs/msteams-docs/commits/master/msteams-platform/tutorials/upgrade-using-yeoman.md
- Title: Tutorial - Upgrade Teams using Microsoft Teams Yeoman generator
-description: Learn how to use Microsoft Teams Yeoman generator to upgrade Teams.
---
-# Upgrade Teams using Microsoft Teams Yeoman generator
-This tutorial helps you to upgrade your current Microsoft Teams app version to the latest version using the Microsoft Teams Yeoman generator.
-
-## Get current version of Teams
-```PowerShell
- yo teams --version
-```
-
-## Update Teams
-The yo command lists out various options ranging from creating project to updating generator. Use the following command to select update generator:
-```PowerShell
- yo
-```
-
-Use the arrow keys to choose **Update Generators**.
-![image of YoSelectUpdatGen](~/assets/images/Update-Teams/YoSelectUpdateGen.png)
-
-The list displays all the available generators. To select or unselect Teams version from the available options, use the **space bar** and choose a specific generator.
-![image of UseSpaceToSelectGenerators](~/assets/images/Update-Teams/UseSpaceToSelectGenerators.png)
-
-It takes few seconds to minutes for Teams installation to complete.
-
-After the installation is complete, use the following command to check the installed version:
-
-```PowerShell
-yo teams --version
-```
-
-![image of FindVersionAfterInstallation](~/assets/images/Update-Teams/FindVersionAfterInstallation.png)
-
-Congrats! You have upgraded Microsoft Teams.
-