📘

This method is only applicable for customers hosted in the US commercial data centers. For all other regions, use the Non-App Store guide.

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

(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.

1. Navigate to https://admin.teams.microsoft.com/.

2. Go to the dashboard on the left → Select Teams apps> Setup policies -> Add New Policy.

3. 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.

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.

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

1. Visit admin.teams.microsoft.com.

2. From the options on the left, select Teams apps ⇨ Setup policies.

3. Click on the Global (Org-wide default) policy and then click Edit.

   

4. 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

1. Visit admin.teams.microsoft.com.
2. From the options on the left, select Teams apps ⇨ Setup policies.
3. 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)
4. Toggle the order of the apps so that the installed bot application is below the Chat option.

5. 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..

2. 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
      

Appendix

(Optional) Removing Specific Permissions from the Moveworks ServicePrincipal

There may be cases where you want to remove some of the default permissions from the bot for your tenant for security purposes. Please note that the following permissions are mandatory for the Teams bot to work:

• 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.

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.

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.

Q: How can I troubleshoot why a specific user still doesn't see the bot in Teams?

A: You can use the Get-CSUserPolicyAssignment command to see which App Permission Policies and App Setup Policies are currently assigned to a user. Note that it can take up to 72 hours for policy assignments to apply to all members of your tenant.