--- title: Multi-Tenant Chat Moveworks Setup Guide deprecated: false hidden: false metadata: robots: index --- ## Overview This guide explains how to enable users to access the same Moveworks bot from multiple Teams tenants or Slack instances within a single Moveworks organization. **Example Use Case:** Connect Moveworks Commercial (Prod US) to both Azure Commercial and a separate Azure tenant (e.g., GCCH) simultaneously. --- ## Critical Considerations ### 1. Identity Resolution Users must be joinable across tenants using a single key to ITSM/IDAM systems. Choose one approach: #### Option A - Employee ID/GUID (Recommended) - Add `employeeID` or GUID to the new tenant and ITSM - Use this consistent identifier for joining user records #### Option B - Email Prefix Standardization with SwapEmailDomainConverter - **Use this when:** Chat tenant email domain ≠ ITSM email domain - **Example scenario:** Users have `user@company.com` in ITSM but `user@subsidiary.com` in Teams tenant - Use `SwapEmailDomainConverter` to normalize domains during identity merge - Standardizes email prefixes across tenants (e.g., `john` from `john@domain1.com` and `john@domain2.com`) #### Option C - Superset in ITSM - **Use this when:** ITSM contains accounts for all email domains used across all chat tenants - No conversion needed - direct email join works - ⚠️ **Requires ITSM as primary/leftmost identity system** ### 2. Messaging Endpoint Verify the bot forwards to the correct Moveworks endpoint (Commercial, GCCH, EU, CA) based on your deployment. --- ## Implementation Steps Replace Graph/Teams with your chat system equivalent as needed. **Navigation:** Setup → Manage Connectors → System Connectors 1. Click "Add Connector" 2. Select **MS Teams** connector 3. Name it for the second tenant (e.g., `msteams_tenant_2_name`) 4. Complete the connector configuration 5. This connector handles bot messaging for the new tenant **Navigation:** Setup → Manage Connectors → System Connectors 1. Click "Add Connector" 2. Select **MS Graph** connector 3. Name it for the second tenant (e.g., `msgraph_tenant_2_name`) 4. Complete authentication and permissions 5. This connector handles identity/user data ingestion from the second tenant **Navigation:** Setup → User Identity → Import Users 1. Click "Add Identity Source" 2. Select the new MS Graph connector (`msgraph_tenant_2_name`) as the source 3. Configure identity ingestion from the second tenant 4. Add the `user_id_info.channel_id_info` for the `msteams_tenant_2_name` connector - **Note:** The channel will still be `MSTEAMS` even though it's a different tenant 5. Save the configuration **Navigation:** Setup → User Identity → Advanced Settings → Service Account 1. Locate the service account user configuration 2. Add a new `channel_id_info` entry for the second Teams tenant: ```json "channel_id_info": [ { "integration_id": "msteams", "user_channel_id": "28:{{BOT_ID_INSTANCE_ONE}}" }, { "integration_id": "msteams_tenant_2_name", "user_channel_id": "28:{{BOT_ID_INSTANCE_TWO}}" } ] ``` 3. Replace `{{BOT_ID_INSTANCE_ONE}}` and `{{BOT_ID_INSTANCE_TWO}}` with your actual bot IDs 4. Save the configuration **Navigation:** Setup → Manage Chatbots → Chatbots 1. Click "Add New Chatbot" 2. Configure for the new Teams tenant 3. Select the MS Teams connector created in Step 1 (`msteams_tenant_2_name`) 4. Complete the chatbot configuration 5. **Important:** Note the `integration_id` for use in later steps **Navigation:** Setup → User Identity → Import Users ⚠️ **Only required if using Option B** (email domains differ between chat tenant and ITSM) 1. Locate the identity source for the second tenant 2. Add `SwapEmailDomainConverter` 3. Configure the domain mapping: - **Source domain:** `subsidiary.com` (Teams tenant domain) - **Target domain:** `company.com` (ITSM domain) 4. This ensures `user@subsidiary.com` (Teams) joins with `user@company.com` (ITSM) **Skip this step if:** - Using Option A (Employee ID/GUID join) - Using Option C (ITSM has all email domains) - Email domains already match between chat tenant and ITSM **Navigation:** Setup → User Identity → View Users 1. Search for test users from each tenant 2. Verify expected users in each tenant have a valid `channel_id` for each integration 3. Confirm both `integration_id` values appear in user records 4. Verify identity ingestion ran correctly **Navigation:** Setup → AI Assistant → Notification Routes 1. Set bot channel preference order 2. **Priority order matters:** List most-restricted tenant first - **Example:** Tenant 2 first (subset of users), then Tenant 1 (all users) 3. The system will notify users on the first available channel according to this priority **Navigation:** Setup → AI Assistant → Employee Communications 1. Configure route preferences using `integration_id` 2. Set up outbound messaging for both tenants 3. Test outbound notifications to both tenants --- ## Validation Checklist Use this checklist to ensure all configuration steps are complete: - [ ] MS Teams connector added for second tenant - [ ] MS Graph connector added for second tenant - [ ] Identity source configured in Import Users for second tenant - [ ] Service account updated with new `channel_id_info` entry - [ ] Chat Bot config created with unique `integration_id` - [ ] Identity conversion configured (only if email domains differ) - [ ] Roster shows users with both channel IDs - [ ] Notification routes prioritized correctly - [ ] Test inbound messages from both tenants - [ ] Test outbound notifications to both tenants --- ## Common Issues & Troubleshooting | Issue | Potential Cause | Solution | |-------|----------------|----------| | Bot doesn't respond in Tenant 2 | Incorrect messaging endpoint or `integration_id` | Verify messaging endpoint configuration and confirm `integration_id` matches in Chat Bot config | | Users not found | Identity merge failure | Verify identity conversion settings and check roster merge configuration | | Wrong bot receives notifications | Incorrect notification route priority | Review notification route priority order - most restrictive tenant should be first | | Identity merge failures | Missing or incorrect SwapEmailDomainConverter | Confirm SwapEmailDomainConverter is configured if email domains differ between systems | | Missing channel IDs | Service account not updated | Verify service account has `channel_id_info` entries for both tenants | | Service account messages fail | Incorrect `integration_id` or bot_id | Confirm service account `channel_id_info` includes correct `integration_id` and bot IDs | --- ## Additional Resources - MS Teams Connector Documentation - MS Graph Connector Documentation - Identity Resolution Best Practices - Notification Routes Configuration --- ## Support If you encounter issues not covered in this guide, please contact Moveworks Support with: - Screenshots of your connector configurations - Roster validation results - Error messages or logs - Test user examples from both tenants