Prerequisite

As part of this set up process, you will need a Microsoft 365 Admin to consent to the following mandatory permissions:

• User.Read.All (Application Permission) is mandatory for purposes of identifying who a user is when they are messaging the bot in Microsoft Teams.
• TeamsAppInstallation.ReadWriteSelfForUser.All (Application Permission) - Is mandatory for the Moveworks bot to proactively message users in Microsoft Teams.

As part of the set up process, you can also allow the following optional permission:

• Group.ReadWrite.All (Application Permission) - is optional, and only required if your organization will be leveraging the bot for Group Management.
• DeviceManagementApps.Read.All (Application Permission) - is optional, and only required if you would like the Moveworks bot to serve deep links to items on your Intune Company Portal.
• Files.Read.All (Application Permission) - is optional, and only required if your organization will be leveraging the bot for Sharepoint File search feature (limited preview).
• Groups.Read.All (Application Permission) - is optional, and only required if your organization will be leveraging the bot for mirroring Sharepoint permissions for File search feature (limited preview).
• Sites.Read.All (Application Permission) - is optional, and only required if your organization will be leveraging the bot for Sharepoint Knowledge Ingestion capabilities.

Teams App Store Bot Installation

1. Under Manage Apps, search for Moveworks (Note: The Moveworks bot will say No under Custom app)
   NOTE: If you cannot find the app in the Microsoft Teams App Store, try navigating to the AppSource Store: https://appsource.microsoft.com/en-us/product/office/WA200002149?tab=Overview
   
2. Once you have added the bot to your tenant, you will need to authorize the API scopes for the app. To do this, navigate to the following URL, replace <TENANT_ID> with the ID of the tenant you are installing the bot to:
   1. https://login.microsoftonline.com/<CUSTOMER_TENANT_ID>/adminconsent?client_id=b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0&state=12345&redirect_uri=https://www.moveworks.com/msteamsd
3. Select Grant admin consent
4. Once you have granted admin consent, send your Customer Success Team your Tenant ID to validate the connection from Moveworks to your Microsoft Tenant works as expected.
5. Once the connection has been validated, your Moveworks Customer Success Team will let you know when your bot is activated and ready to be used.

🚧

Note: If you cannot find the bot under Enterprise Application, try: https://login.microsoftonline.com/<CUSTOMER_TENANT_ID>/adminconsent?client_id=b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0&state=12345&redirect_uri=https://www.moveworks.com/msteamsd

Customizing your Bot

After you’ve installed your bot into Microsoft Teams. You can customize your bot as your organization sees fit. Most customers will build a custom Avatar, and select a custom name for their version of the Moveworks bot. The instructions below outline how to update the name, description, and image of your organization’s Moveworks bot.

1. Click here to navigate to the Manage Apps section of Microsoft Teams: https://admin.teams.microsoft.com/policies/manage-apps
2. Search for Moveworks, and select the bot by clicking on Moveworks.
   
3. Select the pencil icon to customize the settings of your bot.

4. A pop up should appear on the right side, which allows you to customize the name and other details of the bot.

5. After you’ve customized your name, and description, if you scroll down further, there will be settings to customize the images and other colors.

   1. For the main icon, use one full-color icon (192x192) pixel in PNG format.

   2. For the outline icon, use one transparent outline (32x32) pixel in PNG format.

6. After you are done customizing the details of your bot, click on the Apply button on the bottom.

Removing Specific Permissions from Azure (Optional)

There may be cases where you want to remove some of the default permissions from the bot for your tenant for security purposes. By default, the bot requests for the following permissions:

• User.Read.All (Application Permission) is mandatory for purposes of identifying who a user is when they are messaging the bot in Microsoft Teams.
• TeamsAppInstallation.ReadWriteSelfForUser.All (Application Permission) - Is mandatory for the Moveworks bot to proactively message users in Microsoft Teams.
• Group.ReadWrite.All (Application Permission) - is optional, and only required if your organization will be leveraging the bot for Group Management.

For more details refer to the Microsoft Graph Permissions Reference

Appendix

How to Remove Permissions from the Moveworks ServicePrincipal

If you are not going to leverage a specific permission, you can remove the permission from the application using Azure Powershell. The instructions below walk through the steps:

1. Launch Azure AD: Connect-AzureAD
2. Get the ServicePrincipal Object for Moveworks e.g: $sp = Get-AzureADServicePrincipal -filter "displayName eq 'moveworks-teamsappstore-prod'"

3. Find the assigned permissions to the ServicePrincipal e.g: Get-AzureADServiceAppRoleAssignedTo -ObjectId $sp.ObjectId -All $true | Where-Object { $_.PrincipalType -eq "ServicePrincipal" } | ConvertTo-JSON
4. Find the ID of the permission that you want to remove using the table below.

5. Grab the objectId corresponding to the id based on the table above. You can assign that value to a variable$permissionObjectId.
6. Remove the permission e.g: Remove-AzureADServiceAppRoleAssignment -ObjectId $sp.ObjectId -AppRoleAssignmentId $permissionObjectId(you can repeat this step for any other permissions you would like to remove)
7. Validate the permissions have been removed by fetching the ServicePrincipal Object permissions again. e.g: Get-AzureADServiceAppRoleAssignedTo -ObjectId $sp.ObjectId -All $true | Where-Object { $_.PrincipalType -eq "ServicePrincipal" } | ConvertTo-JSON

FAQ:

Q: Can I install more than one Moveworks App on the tenant?

A: No, currently there can only be one installation of Moveworks in each Microsoft Tenant.

Q: Can I use this method of installation if my Moveworks tenant is not hosted in the US?

A: No, currently the Moveworks App Store Teams bot will only work if your Moveworks bot is hosted within Moveworks Commercial Region.