Microsoft Teams Bot (GCCH) Setup Guide

Suggest Edits

This guide will walk you through the process of setting up a Microsoft Teams bot for Moveworks in your Microsoft Teams GCCH Tenant. Once you set up the bot, you will need to provide the following details to your Customer Success team.

Microsoft Graph App ID
Microsoft Graph Tenant ID
Microsoft Graph Secret Value
Teams App Link (to retrieve the app GUID)

The Customer Success team will provide a secure email that you can use to transfer the above information to Moveworks.

Prerequisites

Ensure that you have a Microsoft Azure Pay-As-You-Go subscription already setup (or some other subscription)
1. The subscription must be applied under the global subscription filter.
2. If it is not, search for the Directory + Structure configuration page and enable the subscription so that it shows up globally.
Ensure that you have administrative rights to the main tenant in Microsoft Azure console
1. This includes the ability to create resource groups under the above subscription
Ensure that you have a Teams administrator that can create and manage applications and setup policies

Capturing the Tenant ID

You can find the Tenant ID prior to the call by visiting the following URL. Replace <domain_name> with your company domain name.

https://login.microsoftonline.com/<domain_name>/.well-known/openid-configuration

You will receive a JSON response. Look for the key token_endpoint and find the Tenant ID in the url.

{"token_endpoint":"https://login.microsoftonline.com/<tenant_id_here>/oauth2/token" ….Create the Bot in Your Tenant as an Azure Resource

Navigate to https://portal.azure.us/#create/Microsoft.BotChannelRegistration
Fill out the information as follows:
1. Bot handle - should be named the bot name that was approved
  1. You can use “Moveworks” as a placeholder if this has not been decided
2. Subscription - this should default to "Pay-as-you-go” or another subscription that you have available.
3. Resource Group - create new group for the bot
4. Resource Group Location - choose lowest latency
  1. For example: "West US 2" if you are on the west coast, or "East US 2" if you are east coast based.
5. Pricing tier - set this to F0 (this is a free tier)
  1. Note: While the licensing structure is pay-as-you-go for messages in premium channels, it is unlimited for standard channels such as MS Teams. Therefore when choosing F0 as the pricing tier, the bot resource does not cost anything and the bot will not incur any additional fees (resource groups are also free). For more information, see this page.
6. Messaging Endpoint leave this blank for now and we will revisit it later in the configuration
Under Microsoft App ID,
1. Type of app - select Multi Tenant for the selection.
  1. Note: Multi Tenant is a required setting, since many of the Microsoft Teams backend endpoints use botframework.com as the domain.
Select Create new Microsoft App ID and hit Review + create
1. You will see “Validation Passed“
2. After reviewing the selections, hit Create and your deployment will be in process

Configure the bot settings

Find the Bot Channel Registration/WebApp Bot that was created by waiting for the deployment to finish and then clicking on the “Go to resource” button. Or by searching for the bot by name in the Azure console.

Navigate to Bot Profile on the left hand pane
Set the Display name of the bot to the approved bot name or set this to “Moveworks” temporarily, then click the Apply.
Navigate to Configuration on the left hand pane
Add the URL https://app.moveworksgov.ai/<MSAppID>/api/messages where <MSAppID> is the string in the "Microsoft App ID" shown in the grey box under the Messaging Endpoint.

Example

Grant API Permissions to Microsoft Graph token

Generate Secret

Click on Manage (shown in parenthesis beside the Microsoft App ID title) in the screenshot above.
Select Certificates and Secrets on the left hand pane.
Under Client Secrets select New client secret
Enter a name such as “Moveworks Bot” and set the expiration for 2 years.
Copy the Secret value and save it to provide to the Moveworks Customer Success team via secure email
1. Make sure you do not skip this step as the Client Secret value will be blocked from plain text view after

Add API Permissions

Navigate to API Permissions on the left hand pane.
Select Add a Permission and choose Microsoft Graph.
On the Request API Permissions screen, select MS Graph, and add the necessary permissions for the Teams bot as Application Permissions.
1. User.Read.All
2. TeamsAppInstallation.ReadWriteSelfForUser.All
(Optional) If you are utilizing the Office 365 integration in Moveworks for Microsoft Graph Group Management, Sharepoint Site Ingestion, or Intune integration, please add the following permission based on the feature set you are implementing:
1. Provision access to/create Office 365 groups:
  1. Group.ReadWrite.All
2. Display end-user facing Sharepoint articles as an IT knowledge base:
  1. Sites.Read.All
3. To direct users to apps or device actions in the InTune Company Portal:
  1. DeviceManagementApps.Read.All
4. Ensure all permissions have admin approval granted. Once granted the green
Ensure all permissions have admin approval granted. Once granted the green check mark should appear.

Verify the Azure Manifest

Under the credentials/configuration section, navigate to the Manifest section and verify signInAudience is set to AzureADandPersonalMicrosoftAccount.

Add the Microsoft Teams Feature Channel

Navigate back to your Bot Channel Registration configuration.
Select the Channels tab on the left. Beneath "Add a feature channel", select the Microsoft Teams icon and on the next screen, click "Save".

Provide the Credentials to the Moveworks Customer Success team

If you have not received the secure email, contact your Moveworks Customer Success team and let them know that you have completed the MS Teams bot setup in Azure. They will provide a secure email requesting the following:

Microsoft Graph App ID
Microsoft Graph Tenant ID
Microsoft Graph Secret

Add the Bot to Your Organization in Teams

Once you provide the Customer Success team with the necessary information, the Customer Success team will send you the assets to allow you to create an MS Teams Bot. These assets typically include:

color.png - the color bot icon (192 x 192)
outline.png - the sidebar outlined bot icon (32 x 32)
manifest.json - the bot configuration

Using the following file template to create the manifest.json file, replace the <MSAP_ID> and `<BOT_NAME>` text in the template below, with your Microsoft App ID and the name of your bot respectively. If you have not decided on a name yet, you can use the name “Moveworks” as a temporary placeholder name.

Note: As of 05/12/2022 - manifest Version 1.10 is the highest version recommended in GCCH

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.10/MicrosoftTeams.schema.json",
    "manifestVersion": "1.10",
    "version": "1.0.0",
    "id": "<MSAP_ID>",
    "packageName": "com.moveworks.bots",
    "showLoadingIndicator": false,
    "developer": {
        "name": "Moveworks.ai",
        "websiteUrl": "https://www.moveworks.ai",
        "privacyUrl": "https://www.moveworks.com/privacy-policy",
        "termsOfUseUrl": "https://www.moveworks.com/terms",
        "mpnId": "6107273"
    },
    "icons": {
        "color": "color.png",
        "outline": "outline.png"
    },
    "name": {
        "short": "<BOT_NAME>",
        "full": "<BOT_NAME>"
    },
    "description": {
        "short": "An artificial intelligence chatbot that can assist you with IT-related issues.",
        "full": "Hi! I am <BOT_NAME>, an artificial intelligence (AI) chatbot that can assist you with IT-related issues. I can answer IT questions and help manage any service requests you have."
    },
    "accentColor": "#000000",
    "bots": [
        {
            "botId": "<MSAP_ID>",
            "scopes": [
                "personal",
                "team"
            ],
            "supportsFiles": false,
            "isNotificationOnly": false
        }
    ],
    "permissions": [
        "identity",
        "messageTeamMembers"
    ],
    "validDomains": [
				"*.moveworks.ai",
        "*.moveworks.io",
        "*.moveworks.com",
        "*.*.moveworks.ai",
        "*.*.moveworks.io",
        "*.*.moveworks.com",
        "*.*.*.moveworks.ai",
        "*.*.*.moveworks.io",
        "*.*.*.moveworks.com"
    ],
    "webApplicationInfo": {
        "resource": "https://moveworks.ai",
        "id": "<MSAP_ID>"
    },
    "configurableProperties": [
        "name",
        "shortDescription",
        "longDescription",
        "smallImageUrl",
        "largeImageUrl",
        "accentColor",
        "developerUrl",
        "privacyUrl",
        "termsOfUseUrl"
    ]
}

Prepare the Assets For Microsoft Teams.

Zip the color.png, outline.png, and manifest.json files into a single zip file

Example color.png file:

Example outline.png file (the file is transparent, so hard to see):

Notes:

This must be done on the same operating system that you will add the application from
- If the files are zipped on a Mac, they must be uploaded to the Microsoft Teams app on a Mac. Vice-versa for Windows systems.

Do not place the items into a folder before zipping. Simply select the three files and compress them.

Do not rename any of the files - the Teams client will expect the files to be named as listed above.

Deploy the Bot to Microsoft Teams

Open the Microsoft Teams Desktop App
Click on Apps (on bottom left corner)

Click on Manage your apps

Click Upload an app

Select Submit an app to your org and then select the zip file that you generated

Click on Install

Get the Microsoft Teams Application GUID

Go back to the apps section of Microsoft Teams
Click on Built for your org

Select your new bot

Click the link icon to copy link

Send this link to your Customer Success team so that they can retrieve the GUID from it.

Ensure Proper Networking Allowlist Rules

If you are leveraging a Firewall, CASB, or VDI, and have another layer of network firewall rules. Ensure the following Moveworks owned domain is in an allowlist so that Moveworks can render content in Microsoft Teams Task Modules.

https://app.moveworksgov.ai

(Optional) Apply a Custom App Policy

Moveworks is able to ensure that the bot’s functionalities are only accessible by approved users during development. The bot will be visible in the MS Teams app store but users will not be able to communicate with it.

In some cases our customers would like to have more granular control over this access. You can do this in the Microsoft Teams Administration Console.

Navigate to https://admin.teams.microsoft.com/
Go to the dashboard on the left → Select Teams apps> Setup policies -> Add New Policy

Create a custom app policy to allow the bot you just created
1. NOTE: If a user is assigned a custom policy, that policy applies to the user. If a user isn't assigned a custom policy, the global policy applies to the user. This means if the org is using custom app setup policies already, then you will need to add the bot to all the app setup policies.
2. Please ensure that your Customer Success team is aware of any custom policies

Pre-launch Steps

The steps below should be completed when the bot is ready for go-live.

Pin the App to the Microsoft Teams Sidebar

Pin for all employees

Visit admin.teams.microsoft.com
From the options on the left, select Teams apps ⇨ Setup policies
Click on the Global (Org-wide default) policy and then click Edit
Toggle the order of the apps so that the installed bot application is below the Chat option

Pin Teams app for a specific group of users

Visit admin.teams.microsoft.com
From the options on the left, select Teams apps ⇨ Setup policies
Click on the + Add button to create a new Teams app setup policy (more info here: https://docs.microsoft.com/en-us/MicrosoftTeams/teams-app-setup-policies)
Toggle the order of the apps so that the installed bot application is below the Chat option

Now you can select which users you want this specific policy to apply to. There are two options here - manual method and a Powershell method.
1. Option A: Manually enter users to add to the policy
  1. Go back to the Setup policies page, select the newly created App setup policy and click Manage Users
  2. Enter the names of users you want the policy to apply to. Click Apply

Option B: Create policy for a specific group of users in Azure using Powershell
1. Locate your group in Azure that you want to apply the policy to. Copy the object id for the group
2. Open Powershell and enter the following commands. Once complete this can take up to 72 hours to take effect, depending on the size of the group. See here for more information.
```
New-CsGroupPolicyAssignment -PolicyType TeamsAppSetupPolicy -GroupId <group_id> -PolicyName "Moveworks Bot Users" -Rank 1

Get-CsGroupPolicyAssignment -GroupId <group_id>
```
  Replace the group_id with the correct value above. The group_id is the Azure object id and “Moveworks Bot Users” is the name of the policy you used in the previous step.Example based on above:
```
New-CsGroupPolicyAssignment -PolicyType TeamsAppSetupPolicy -GroupId 57cdf267-5ab7-43bc-b7ad-4c55cc905e40 -PolicyName "FirstLineWorker" -Rank 1

Get-CsGroupPolicyAssignment -GroupId 57cdf267-5ab7-43bc-b7ad-4c55cc905e40
```

Pinned App FAQ

Q: Can a user unpin the bot in Teams?

A: Moveworks Bot can be unpinned from the sidebar in Microsoft Teams by the user.

Q: What's the behavior in Teams?

A: Moveworks Bot will remain removed from the current Teams session, however once the user logs out of teams and logs back on the app setup policy kicks in and re-adds Moveworks Bot.

Q: Can a user move the left sidebar icon around?

A: user can move the Moveworks Bot around in the left side bar, however the App Setup Policy will overwrite this once the user logs off and logs back onto teams.

Contacting Us

You can reach the Customer Success team anytime at [email protected] or over the support channel we establish in your team’s messaging platform.

Updated 8 months ago