Microsoft Teams Bring Your Own App (BYOA) Integration with Simpplr

Table of Contents

• Introduction
• Connect MS Teams account to Simpplr
• Creating a custom app
• Configuring custom app settings in Microsoft
• Connect integration at the user level
• Link MS Teams to a site
• Promoting content to Teams
• Send alerts to Teams

Introduction

In addition to the out-of-the-box MS Teams integration, Simpplr offers a Bring Your Own App (BYOA) integration with Microsoft Teams that exists at the application level, and means that your App manager can bypass the requirements from Simpplr in order to connect the app.

Rest assured the integration will work similarly to the out-of-the-box offering.

Connect your org's MS Teams account to Simpplr

Back to top

To get started, from Simpplr:

1. Navigate to Manage > Application > Integrations > Messaging.
2. Click on the Microsoft Teams check box.
3. You will be asked to authorize access to declared permissions. To do this, you'll need to have a Microsoft Teams account with Teams Administrator and Application Administrator roles.
   
4. Accept the following permissions on behalf of Simpplr. The requested permissions are explained in the image below.

   Detailed description of scopes

   Scope Name	Scopes Used	Permission type	Description	API Documentation Path	API
   Maintain access to data you have given it access to	offline_access	Delegated	The offline_access scope gives your app access to resources on behalf of the user for an extended time. On the consent page, this scope appears as the Maintain access to data you have given it access to permission.
   Send channel messages	ChannelMessage.Send	Delegated	Allows an app to send channel messages in Microsoft Teams, on behalf of the signed-in user	https://docs.microsoft.com/en-us/graph/api/channel-post-messages?view=graph-rest-1.0&tabs=http	https://graph.microsoft.com/v1.0/teams/02bd9fd6-8f93-4758-87c3-1fb73740a315/channels
   Read all app catalogs	AppCatalog.Read.All	Application	Allows the app to read apps in the app catalogs without a signed-in user	https://docs.microsoft.com/en-us/graph/api/appcatalogs-list-teamsapps?view=graph-rest-1.0&tabs=http	https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/$%7BteamsAppsId%7D
   Read all groups	Group.Read.All	Application	Allows the app to read group properties and memberships, and read conversations for all groups, without a signed-in user	https://learn.microsoft.com/en-us/graph/api/teamsapp-publish?view=graph-rest-1.0&tabs=http
   Submit application packages to your organization's catalog and cancel pending submissions	AppCatalog.Submit	Delegated	Allows the app to submit application packages to the catalog and cancel submissions that are pending review on behalf of the signed-in user	https://learn.microsoft.com/en-us/graph/api/teamsapp-publish?view=graph-rest-1.0&tabs=http
   Read and write to all app catalogs	AppCatalog.ReadWrite.All	Delegated	Allows the app to create, read, update, and delete apps in the app catalogs without a signed-in user	https://learn.microsoft.com/en-us/graph/api/teamsapp-publish?view=graph-rest-1.0&tabs=http
   	TeamsAppInstallation.ReadWriteForUser.All	Application	Allows the app to read, install, upgrade, and uninstall Teams apps for any user, without a signed-in user. Does not give the ability to read application-specific settings	https://docs.microsoft.com/en-us/graph/api/userteamwork-post-installedapps?view=graph-rest-1.0&tabs=http	https://graph.microsoft.com/v1.0/users/$%7BaliasUpnOrOid%7D/teamwork/installedApps
   	TeamsAppInstallation.ReadWriteSelfForTeam.All	Application	Allows a Teams app to read, install, upgrade, and uninstall itself in any team, without a signed-in user	https://docs.microsoft.com/en-us/graph/api/team-post-installedapps?view=graph-rest-1.0&tabs=http	https://graph.microsoft.com/v1.0/teams/$%7BteamUuid%7D/installedApps
   	email	Delegated
   	openId	Delegated

   1. Once you've accepted permissions, you'll be redirected back to Simpplr. A new app is created for your Simpplr instance on the backend of MS Teams.
   2. Choose an app name, branding icon and color for your newly created Simpplr app in Teams. This will determine how the App is shown within Teams, and can be modified at any time from this menu. The App name should be something like CompanyName_Simpplr or CompanyName_IntranetName.
   3. Recommended practice is to enable the option for users to share Alerts to Teams channels. You can switch this option on or off. Enabling it will only open the option for users to share Alerts; it does not mean Alerts will be shared by default. 

   Note:

   No users will be able to connect at the user profile level until the app has been successfully created. This can sometimes take up to 24 hours. To view the app's status, head to your Teams account and check out the Apps menu.

Creating a custom app

Once you've given consent, you'll be asked to create your own custom App. Fill in basic details like appName, appIcon and branding. Simpplr will create the app on your org's behalf in your Microsoft Teams catalog. This app will be accessible only to you.

Configure custom app settings

1. Once the app is created successfully, as the Microsoft Global Admin, you'll need to log in to the Microsoft Teams Admin centre.
2. Since the app created is a custom app, few settings are to be made for the custom app to be available to use. Navigate to Manage Apps. Click on Actions in the right corner and choose Org wide app settings.
   
3. Scroll down to Custom app in Org wide app settings and enable the option for users to install the app and save the changes.
   
4. From the same page, in the Search bar, search the app you just created and click on it.
   
5. The App detail page will open. From the right corner, click on Actions and make sure the app is not blocked. If blocked, then unblock it.
   
6. Click on the Permissions tab and provide consent to the permissions. Consent to permissions in the admin center can only be given by a Global Admin user.
   
7. Once the consent is given, the custom app is created will be available to use.

The Global Admin is required to log in to the admin center and give consent because Simpplr has a few permissions where Admin consent is required. Those permissions are:

• TeamsAppInstallation.ReadWriteSelfForTeam.All, TeamsAppInstallation.ReadWriteForUser.All, AppCatalog.ReadWrite.All

Connect integration at the user level

Back to top

Note:

The first person to connect at the user level must be the Microsoft Admin user for your org.

To connect at the profile level:

1. Go to your user menu, then Profile & settings. Click Edit profile & settings.
   
2. Click the External apps tab and choose Connect account in the Microsoft Teams label. Follow the requested prompts from Simpplr to connect.
   
3. The Admin user will need to accept the permissions Simpplr is requesting from Microsoft, as shown in the image above.
   
4. The End user will need to accept the permissions shown below.
   

Link MS Teams to a site

Back to top

For a site to post MS Teams content, it must first be linked to a Team. To do so:

1. Go to Manage site > External apps.
2. Enable Microsoft Teams, select which site activity you want posted in Teams.
3. In the Team dropdown, select a Team to link to the site. 

In the Channel dropdown, select a channel to link to the site.

Promoting content to Teams

Back to top

Once enabled at the App management level, all Content managers will begin to see the option to post to Teams when publishing content. If the Content manager has also connected their account, they will be able to select the Team and the channel to post the content to. If they haven't connected their Teams account, this option will be disabled and they'll be prompted to connect their account.

In addition to newly published content being promoted, all existing content will be able to be promoted by content managers at any time.

Sharing content to Teams

All users that have connected their Teams account will be able to click the share icon and select to share the content to a specified Team and channel.  

All Simpplr content will unfurl for all users in the channel without any secondary connection to Simpplr. However, Private and Unlisted site content will show a message stating that a preview is unavailable.

Note:

Feed posts from a site will automatically display on the Teams channel once connected to that site. See the image below for an example of feed posts being shared to the site. 

Teams channel display

Once posted to a Teams channel, the post will be made on behalf of the user. It will show the user's icon and Teams name just as if they had pasted the link themselves.

Click to chat

When a user has connected their account, their MS Teams user name will appear on their profile and all search results. This is a clickable link that will open MS Teams and enter a chat with the given user.

Note, if you've never chatted before with the user you selected, Teams will open at the Recent conversation menu, not that user's chat menu. This is a known issue currently being addressed for an upcoming release. 

Send alerts to MS Teams

Back to top

If enabled in the Manage > Application menu, Alerts can be configured to be sent to select MS Teams channels. To do so:

1. Go to your user menu > Alerts. Click Add alert.
2. Configure the alert. 
3. Under External distribution, select Microsoft Teams. 
4. Choose whether to directly notify recipients in Teams, or post the alert in the Teams channel. If both are selected, MS Teams users will receive two alerts.

Select the Team and channel for the alert. Click Display alert.