diff --git a/content/in-app-ui/react/overview.mdx b/content/in-app-ui/react/overview.mdx index 4027ff88..b8a0c4f3 100644 --- a/content/in-app-ui/react/overview.mdx +++ b/content/in-app-ui/react/overview.mdx @@ -38,6 +38,7 @@ The Knock React SDK ships the following pre-built UI elements: ### TeamsKit +- `MsTeamsChannelCombobox`: for picking one or more Microsoft Teams channels to route notifications to. - `MsTeamsAuthButton`: for managing the OAuth process between your Microsoft Teams bot and your customer's Microsoft Entra tenant. ## Hooks for headless UI diff --git a/content/in-app-ui/react/teams-kit.mdx b/content/in-app-ui/react/teams-kit.mdx index d21a2621..f61835e9 100644 --- a/content/in-app-ui/react/teams-kit.mdx +++ b/content/in-app-ui/react/teams-kit.mdx @@ -4,7 +4,7 @@ description: How to let users connect to your Microsoft Teams integration with K section: TeamsKit --- -Our `@knocklabs/react` library comes with pre-built components for allowing your users to connect their Microsoft Teams instances to Knock. TeamsKit manages your OAuth connection and tokens, and integrates seamlessly with the rest of Knock. +Our `@knocklabs/react` library comes with pre-built components for allowing your users to connect their Microsoft Teams instances to Knock and select the channels they want to be notified on. TeamsKit manages your OAuth connection and tokens, helps your customers select which channels they want to receive notifications in, and integrates seamlessly with the rest of Knock. ## Getting started @@ -17,7 +17,7 @@ Depending on your use case, you can follow one of these guides for step-by-step ## Using TeamsKit components -Once you've provided access to the necessary data, you can drop Knock's pre-built components into your React application to immediately set up Microsoft Teams authorization for your users. [See the reference](/sdks/react/reference##microsoft-teams-components) for full documentation of these components. +Once you've provided access to the necessary data, you can drop Knock's pre-built components into your React application to immediately set up Microsoft Teams authorization and channel selection for your users. [See the reference](/sdks/react/reference#microsoft-teams-components) for full documentation of these components. ### Add the providers @@ -117,9 +117,59 @@ Remember to consider which roles in your application can access the `MsTeamsAuth } /> +#### MsTeamsChannelCombobox + +
+ The MsTeamsChannelCombobox component showing connected channels +
+ The MsTeamsChannelCombobox component showing connected channels +
+
+ +This combobox contains the list of teams and channels belonging to the connected Microsoft Entra tenant. Users will use this combobox to search and select a channel (or more than one channel) to be notified when your application triggers a workflow with a Teams channel step. They can also use this combobox to deselect a connected channel. + +The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well. + +Add your combobox to your application where you'd like the user to select channels to notify: + +```javascript title="The MsTeamsChannelCombobox connects an object to one or more channels" + +``` + +
+ + Limitations + + + } +/> + ### Complete sample code -Here's an example of `MsTeamsAuthButton` in a React application. +Here's an example of these components in a React application. ```javascript title="Store Knock and Microsoft Teams credentials as .env vars" // .env @@ -143,6 +193,7 @@ MS_TEAMS_BOT_ID = "f1b85cf4-58e1-4cef-8d3f-ce6ccf60734d"; tenantId={currentAccount.id} > + ``` @@ -164,6 +215,38 @@ const NotificationSettings = () => { }; ``` +
+ +```javascript title="Render an MsTeamsChannelCombobox for each object" + +const VideoProjectsPage = ({videos}) => { + return ( + videos.map(video => { + return + }) + ) +} + +const VideoPage = ({video}) => { + return ( +
+
{video.name}
+
{video.content}
+
{video.comments}
+ +
+ ) +} + +``` + +
+ ## Using TeamsKit headless If you need custom designs or want to display additional information around your Microsoft Teams integration, you don't need to use Knock's pre-built components to take advantage of TeamsKit. @@ -181,6 +264,8 @@ To use a hook in your component, all you need to to is import it and pass it the If you want more fine grain control of your data, you can skip the hooks and simply use the functions Knock exposes in the [`@knocklabs/client` library](https://github.com/knocklabs/javascript/tree/main/packages/client) as long as you wrap the component you're calling it in inside of `KnockProvider`. You can accomplish anything we provide with hooks or the components with the following functions: - `knock.msTeams.authCheck`: Get the status of Microsoft Teams authorization +- `knock.msTeams.getTeams`: Get a list of teams in the connected Microsoft Entra tenant +- `knock.msTeams.getChannels`: Get a list of Microsoft Teams channels within a single team - `knock.msTeams.revokeAccessToken`: Removes the Microsoft Entra tenant ID from the tenant - `knock.objects.getChannelData`: Use this to get the connected channels stored as channel data on the recipient object - `knock.objects.setChannelData`: Use this to set the connected channels for a recipient object or an access token for a tenant @@ -190,13 +275,15 @@ If you want more fine grain control of your data, you can skip the hooks and sim Lastly, you can interact directly with the API endpoints for all of the above functionality. Here are the endpoints used in TeamsKit that you would need to support an implementation of the managed UI: - [Microsoft Teams auth check](/reference#ms-teams-auth-check): status of Microsoft Teams authorization +- [Microsoft Teams teams](/reference#ms-teams-teams): list of teams in the connected Microsoft Entra tenant +- [Microsoft Teams channels](/reference#ms-teams-channels): list of Microsoft Teams channels within a single team - [Microsoft Teams revoke access](/reference#ms-teams-revoke-access): remove a Microsoft Entra tenant ID from a Knock tenant - [Get channel data](/reference#get-object-channel-data): get channel data for your recipient object, which gives you access to the connected Microsoft Teams channels - [Set channel data](/reference#set-object-channel-data): set channel data for your recipient object, which allows you to set connected Microsoft Teams channels ## Resource access grants -The only access you'll need to manage when using TeamsKit are grants for your users to interact with their [Tenants](/concepts/tenants). This is necessary because the user in this context is an end user in your application who does not have access to Knock as a [member of the account](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API. +The only access you'll need to manage when using TeamsKit are grants for your users to interact with their [Tenants](/concepts/tenants) and [Objects](/concepts/objects) in Knock. This is necessary because the user in this context is an end user in your application who does not have access to Knock as a [member of the account](/manage-your-account/managing-members). Therefore, these grants provide them elevated privileges to operate on specific resources using the API. We've made it easy for you to tell Knock which resources your users should have access to by making it a part of their user token. In this section you'll learn how to generate these grants using the Node SDK and, if you're not using the SDK, how to structure them for other languages. diff --git a/content/integrations/chat/microsoft-teams/overview.mdx b/content/integrations/chat/microsoft-teams/overview.mdx index 6d98f14b..a3f8e148 100644 --- a/content/integrations/chat/microsoft-teams/overview.mdx +++ b/content/integrations/chat/microsoft-teams/overview.mdx @@ -189,7 +189,7 @@ Depending on the Microsoft Teams integration you build into your product, you'll If your integration involves a customer connecting a _non-user resource_ in their product (such as a project or a page) to a Microsoft Teams channel, you’ll want to store that channel data [on an object](/reference#set-object-channel-data) in Knock, as it’s not specific to any single user. - For this integration, you'll store a Microsoft Teams `ms_teams_channel_id` in the `MsTeamsConnection` object. + For this integration, you'll store a Microsoft Teams `ms_teams_channel_id` in the `MsTeamsConnection` object. The [`MsTeamsChannelCombobox`](/in-app-ui/react/teams-kit#msteamschannelcombobox) component of Knock's TeamsKit can help you with this. diff --git a/content/integrations/chat/microsoft-teams/sending-a-message-to-channels.mdx b/content/integrations/chat/microsoft-teams/sending-a-message-to-channels.mdx index a970fcde..f4acc239 100644 --- a/content/integrations/chat/microsoft-teams/sending-a-message-to-channels.mdx +++ b/content/integrations/chat/microsoft-teams/sending-a-message-to-channels.mdx @@ -8,14 +8,14 @@ layout: integrations In this guide, we'll cover how to update a multi-tenant Microsoft Teams bot to send messages to channels in Microsoft Teams using Knock. It assumes that you have already created a Microsoft Teams channel in Knock as outlined in the [Microsoft Teams integration overview](/integrations/chat/microsoft-teams/overview) guide. -In this implementation, your application's users will connect their Microsoft Entra tenant to Knock and be able to send messages to public channels. To make this easier to implement, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit) to facilitate the OAuth flow. +In this implementation, your application's users will connect their Microsoft Entra tenant to Knock and be able to send messages to public channels. To make this easier to implement, we'll use Knock's [TeamsKit components](/in-app-ui/react/teams-kit) to facilitate the OAuth flow and channel selection process. Here's what we'll cover in this guide: - Modeling a multi-tenant application in Knock using `Tenants` - Adding required scopes to your Microsoft Teams app's manifest - Implementing a Microsoft OAuth flow using Knock's `MsTeamsAuthButton` component -- Setting required Object channel data when a Microsoft Teams bot is installed in a channel +- Choosing public channels to send messages to using Knock's `MsTeamsChannelCombobox` component - Triggering a workflow with an object recipient to send a message to a Microsoft Teams channel -## Setting Object channel data +### Choosing channels with `MsTeamsChannelCombobox` -Your application should provide a method for admin users to associate a Microsoft Teams channel with a Knock `Object`. Using our repositories example, this might look like a combobox allowing the admin to select one or more Microsoft Teams channels to associate with a repository. (You can use the Microsoft Graph API to retrieve a list of Microsoft Teams channels.) +This combobox contains the list of teams and channels belonging to the connected Microsoft Entra tenant. Users will use this combobox to search and select a channel (or more than one channel) to be notified when an event in your application occurs, for example a comment on a video. They can also use this combobox to deselect a connected channel. -Once the admin has selected one or more Microsoft Teams channels, your backend should update the channel data associated with the `Object`. If you're using Knock's Node SDK, your code might look like this: +The combobox automatically shows which channels are already connected, and gives users an easy way to remove them as well. -```javascript -await knockClient.objects.setChannelData( - "repositories", - "knocklabs/javascript", - process.env.KNOCK_MS_TEAMS_CHANNEL_ID, - { connections: [{ ms_teams_channel_id: msTeamsChannelId }] }, -); +
+ The MsTeamsChannelCombobox component showing connected channels +
+ The MsTeamsChannelCombobox component showing connected channels +
+
+ +Add your combobox to your application where you'd like the user to select channels to notify: + +```javascript title="The MsTeamsChannelCombobox connects an object to one or more channels" + ``` -Here, `KNOCK_MS_TEAMS_CHANNEL_ID` is the channel ID of your Microsoft Teams integration within Knock. `"knocklabs/javascript"` is the ID of the `Object` (in this case, a repository). +
+ + Limitations +
    +
  • + The combobox will only show public channels. Microsoft Teams bots do + not support sending messages to private channels. +
    • +
  • + The combobox does not show individual users for Microsoft Teams direct + messages. +
    • +
+ + } +/> ## Triggering a workflow diff --git a/content/sdks/react/reference.mdx b/content/sdks/react/reference.mdx index 7bd6ffd9..c0684e6c 100644 --- a/content/sdks/react/reference.mdx +++ b/content/sdks/react/reference.mdx @@ -675,8 +675,8 @@ import { Modal } from "@knocklabs/react"; +### `MsTeamsChannelCombobox` + +#### Props + + + + + ## General hooks ### `useAuthenticatedKnockClient` @@ -1038,7 +1050,7 @@ This hook returns partial data about the Slack channels that are present on the @@ -1111,6 +1123,123 @@ Builds a Microsoft Teams authorization URL generator and a disconnect function. /> +### `useMsTeamsTeams` + +This hook will continually fetch partial data about Microsoft Teams teams within a given Microsoft Entra tenant up to the max limit given. + +**Props**: + + + + + +**Returns**: + + + + + + + +### `useMsTeamsChannels` + +This hook will continually fetch partial data about Microsoft Teams channels within a given team. + +**Props**: + + + + + + +**Returns**: + + + + + + + +### `useConnectedMsTeamsChannels` + +This hook returns partial data about the Microsoft Teams channels that are present on the given recipient object's channel data. These are the Microsoft Teams channels that would be notified with this object as a recipient of a workflow. + +**Props**: + + + + + +**Returns**: + + + + + + + + + ## Types ### `I18nContent` @@ -1132,9 +1261,12 @@ interface Translations { readonly read: string; readonly unseen: string; + readonly msTeamsChannelSetError: string; readonly msTeamsConnect: string; readonly msTeamsConnected: string; readonly msTeamsConnecting: string; + readonly msTeamsConnectionErrorExists: string; + readonly msTeamsConnectionErrorOccurred: string; readonly msTeamsConnectContainerDescription: string; readonly msTeamsDisconnect: string; readonly msTeamsDisconnecting: string; @@ -1171,7 +1303,7 @@ interface I18nContent { } ``` -### `QueryOptions` +### `SlackChannelQueryOptions` ```typescript type SlackChannelQueryOptions = { @@ -1206,10 +1338,67 @@ type SlackChannelConnection = { }; ``` -### `ContainerObject` +### `MsTeamsTeamQueryOptions` + +```typescript +type MsTeamsTeamQueryOptions = { + maxCount?: number; // The max number of teams to return; default: 1000 + limitPerPage?: number; // How many teams will be returned per request; default: 100 + filter?: string; // OData $filter query param to filter teams; default: null + select?: string; // OData $select query param to select fields; default: "id,displayName" +}; +``` + +### `MsTeamsChannelQueryOptions` + +```typescript +type MsTeamsChannelQueryOptions = { + filter?: string; // OData $filter query param to filter channels; default: "isArchived eq false and membershipType eq 'standard'" + select?: string; // OData $select query param to select fields; default: "id,displayName" +}; +``` + +### `MsTeamsTeam` + +```typescript +type MsTeamsTeam = { + id: string; + displayName: string; + description?: string; +}; +``` + +### `MsTeamsChannel` + +```typescript +type MsTeamsChannel = { + id: string; + displayName: string; + description?: string; + membershipType?: string; + isArchived?: boolean; + createdDateTime?: string; +}; +``` + +### `MsTeamsChannelConnection` + +```typescript +type MsTeamsChannelConnection = { + ms_teams_tenant_id?: string; + ms_teams_team_id?: string; + ms_teams_channel_id?: string; + ms_teams_user_id?: null; + incoming_webhook?: { + url: string; + }; +}; +``` + +### `RecipientObject` ```typescript -type ContainerObject = { +type RecipientObject = { objectId: string; collection: string; }; diff --git a/public/images/integrations/chat/microsoft-teams/msteamschannelcombobox.png b/public/images/integrations/chat/microsoft-teams/msteamschannelcombobox.png new file mode 100644 index 00000000..ed6cef09 Binary files /dev/null and b/public/images/integrations/chat/microsoft-teams/msteamschannelcombobox.png differ