📘

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 AI Assistant in Microsoft Teams.
• TeamsAppInstallation.ReadWriteSelfForUser.All (Application Permission) - Is mandatory for the Moveworks AI Assistant 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 AI Assistant for Group Management.
• DeviceManagementApps.Read.All (Application Permission) - is optional, and only required if you would like the Moveworks AI Assistant 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 AI Assistant for Sharepoint File search feature (limited preview).
• Groups.Read.All (Application Permission) - is optional, and only required if your organization will be leveraging the AI Assistant 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 AI Assistant for Sharepoint Knowledge Ingestion capabilities.

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.moveworks.ai
  `

Teams App Store AI Assistant Installation

1. Under Manage Apps, search for Moveworks (Note: The Moveworks AI Assistant 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 AI Assistant to your tenant, you will need to authorize the API scopes for the app. To do this, navigate to the following URL, replace \<CUSTOMERTENANT_ID> with the ID of the tenant you are installing the AI Assistant 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 AI Assistant is activated and ready to be used.

🚧

Note: If you cannot find the AI Assistant 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 AI Assistant 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 AI Assistant 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 AI Assistant 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 AI Assistant into Microsoft Teams. You can customize your AI Assistant 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 AI Assistant 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.

Configuring in Moveworks Setup

1. Navigate to Moveworks Setup Portal. Go to Core Platform > Manage Connectors > System Connectors and select Microsoft Teams.

   

2. Click on NEXT: ADD CREDS

   

3. Add a Connection Name and select Authentication Type as Microsoft Bot App Store Auth. Click Save.

   

NOTE: To deploy a Teams AI Assistant application in Moveworks Setup, follow the instructions here.

Pre-launch Steps

The steps below should be completed when the AI Assistant 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 AI Assistant 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 AI Assistant 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 AI Assistant 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 AI Assistant 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) Revoking Specific Permissions from the Moveworks ServicePrincipal

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

• User.Read.All (Application Permission) is mandatory for purposes of identifying who a user is when they are messaging the AI Assistant in Microsoft Teams.
• TeamsAppInstallation.ReadWriteSelfForUser.All (Application Permission) - Is mandatory for the Moveworks AI Assistant 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 the Azure Portal or Azure Powershell. The instructions below walk through the steps:

Revoking Specific Permissions using the Azure Portal

1. Go to Enterprise applications. Search "moveworks-teamsappstore-prod". Select the moveworks-teamsappstore-prod app.

   

2. Go to Security > Permissions for the moveworks-teamsappstore-prod app.

3. Click the three dots to the right of the permission that you would like to revoke and select Remove permission

   

4. Click Yes, revoke on the confirmation prompt.

   

Revoking Specific Permissions using Azure Powershell

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. You can find all MS Graph Permission IDs here.

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 AI Assistant will only work if your Moveworks AI Assistant is hosted within Moveworks Commercial Region.

Q: Can a user unpin the AI Assistant in Teams?

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

Q: What's the behavior in Teams?

A: Moveworks AI Assistant 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 AI Assistant 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 AI Assistant 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.