--- title: Service Account Configuration Guide excerpt: >- Complete guide for configuring Service Accounts in Moveworks Setup with `channel_id_info` and `itsm_id_info` for all systems. deprecated: false hidden: false metadata: robots: index --- ## Overview A service account is required for Moveworks to function properly. Without a configured service account, the user roster cannot be ingested, and the bot cannot perform automated actions on behalf of the system. **Purpose:** * **User Roster Ingestion**: Service Account / Bot User must be present for the User Identity Flow to execute successfully * **Automated Actions**: Enables the bot to create tickets, submit requests, and perform other actions in connected systems * **System Integration**: Links the bot's identity across chat platforms (Teams/Slack), ITSM systems (ServiceNow/Jira), and identity providers (Okta/Azure AD) **What This Configuration Does:** The service account configuration maps the bot's identity across all integrated systems using `channel_id_info` (chat platforms) and `user_itsm_id_info` (ITSM systems). This allows Moveworks to operate as a unified bot identity across your entire stack. *** ## Complete Configuration Example > **Note:** This example includes inline comments for documentation purposes. When creating your actual configuration in Moveworks Setup, remove the comments & sections not relevant to your tech stack. ```json { // ========================================== // Primary email address - the canonical email for this service account // ========================================== "email_addr": "moveworks-bot@company.com", "record_id": "moveworks-bot@company.com", "user_name": "moveworks-bot", "full_name": "Moveworks Bot", "role": "Virtual Assistant (Bot)", "department": "IT", "location": "Mountain View", "user_tags": ["BOT"], "user_id_info": { // ========================================== // Email aliases - all email addresses this account is known by across systems // Used for identity resolution and joining across different systems // Typically from the Identity system (primary source) // ========================================== "user_email": [ "moveworks-bot@company.com", "bot@subsidiary.com" ], "channel_id_info": [ // ========================================== // MS Teams - Primary Tenant // Get Microsoft App ID from MS Teams connector in Moveworks Setup // Format: "28:{microsoft_app_id}" // If installed from MS App Store: "28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0" // ========================================== { "integration_id": "msteams", "user_channel_id": "28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0" }, // ========================================== // MS Teams - Secondary Tenant (GCCH) // Get Microsoft App ID from MS Teams connector in Moveworks Setup // Format: "28:{microsoft_app_id}" // ========================================== { "integration_id": "msteams_gcch", "user_channel_id": "28:87654321-4321-4321-4321-cba987654321" }, // ========================================== // Slack - Primary Workspace // API: GET /api/auth.test (returns user_id and team) // Use: Slack connector in API Playground // Format: "{user_id}:{team_id}" // ========================================== { "integration_id": "slack", "user_channel_id": "U01ABC123:T01ABC123" }, // ========================================== // Slack - Secondary Workspace // API: GET /api/auth.test (returns user_id and team) // Use: Slack connector in API Playground // Format: "{user_id}:{team_id}" // ========================================== { "integration_id": "slack_subsidiary", "user_channel_id": "U02DEF456:T02DEF456" }, // ========================================== // Web Chat // Format: Service account email address // ========================================== { "integration_id": "movewebchat", "user_channel_id": "svc.moveworks@company.com" } ], "user_itsm_id_info": [ // ========================================== // ServiceNow // API: GET /api/now/table/sys_user?sysparm_query=user_name={username}&sysparm_fields=sys_id,user_name,email,first_name,last_name,name&sysparm_limit=1 // Use: ServiceNow connector in API Playground // Alternative query: sysparm_query=email={email} // ========================================== { "integration_id": "snow", "itsm_user_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "external_id": "moveworks.bot", "first_name": "Moveworks", "last_name": "Bot", "full_name": "Moveworks Bot" }, // ========================================== // Jira Service Management // API: GET /rest/api/3/user/search?query={email} // Use: Jira connector in API Playground // Alternative: /rest/api/3/user?accountId={account_id} // ========================================== { "integration_id": "jira_service_desk", "itsm_user_id": "5d8e9f0a1b2c3d4e5f6a7b8c", "external_id": "moveworks-bot@company.com", "first_name": "Moveworks", "last_name": "Bot", "full_name": "Moveworks Bot" }, // ========================================== // Salesforce // API: GET /services/data/v58.0/query?q=SELECT Id,Username,Email,FirstName,LastName,Name FROM User WHERE Username='{username}' // Use: Salesforce connector in API Playground // ========================================== { "integration_id": "salesforce", "itsm_user_id": "0051234567890ABCDE", "external_id": "moveworks.bot@company.com", "first_name": "Moveworks", "last_name": "Bot", "full_name": "Moveworks Bot" }, // ========================================== // FreshService // API: GET /api/v2/requesters?query="primary_email:'{email}'" // Use: FreshService connector in API Playground // ========================================== { "integration_id": "freshservice", "itsm_user_id": "15001234567", "external_id": "moveworks.bot@company.com", "first_name": "Moveworks", "last_name": "Bot", "full_name": "Moveworks Bot" }, // ========================================== // ManageEngine // API: GET /api/v3/users?input_data={"list_info":{"search_criteria":{"field":"email_id","value":"{email}"}}} // Use: ManageEngine connector in API Playground // ========================================== { "integration_id": "manageengine", "itsm_user_id": "158691000000209025", "external_id": "moveworks.bot@company.com", "first_name": "Moveworks", "last_name": "Bot", "full_name": "Moveworks Bot" } ] } } ``` *** ## How to Use API Playground 1. **Navigate to Setup → Manage Connectors → System Connectors** 2. Find the connector for your system (e.g., "MS Teams", "Slack", "ServiceNow") 3. Click **"Test in API Playground"** 4. Enter the API endpoint and parameters from the configuration example above 5. Copy the response values into your service account configuration **Note:** API Playground handles authentication automatically through your configured connector. *** ## API Quick Reference ### Chat Systems | System | How to Get user_channel_id | Format | | ------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | | **MS Teams** | Get Microsoft App ID from MS Teams connector in Moveworks Setup
**If installed from MS App Store**: Use fixed value | `"28:{microsoft_app_id}"`
App Store: `"28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0"` | | **Slack** | API: `/api/auth.test`
Returns: `user_id` (U...) and `team` (T...) | `"\{user_id}:{team_id}"` | | **Web Chat** | Use service account email address | `"email@company.com"` | ### ITSM Systems | System | Endpoint | Search Parameter | Response Field → Config Field | | ---------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **ServiceNow** | `/api/now/table/sys_user` | `sysparm_query=user_name={username}`
`sysparm_fields=sys_id,user_name,email,first_name,last_name,name`
`sysparm_limit=1` | `sys_id` → `itsm_user_id` (32-char hex)
`user_name` → `external_id` | | **Jira** | `/rest/api/3/user/search?query={email}` | Email or username | `accountId` → `itsm_user_id`
`emailAddress` → `external_id`
Parse `displayName` → first/last name | | **Salesforce** | `/services/data/v58.0/query` | `q=SELECT Id,Username,Email,FirstName,LastName,Name FROM User WHERE Username='{username}'` | `Id` → `itsm_user_id` (18-char)
`Username` → `external_id` | | **FreshService** | `/api/v2/requesters` | `query="primary_email:'{email}'"` | `id` → `itsm_user_id` (numeric)
`primary_email` → `external_id` | | **ManageEngine** | `/api/v3/users` | `input_data={"list_info":{"search_criteria":{"field":"email_id","value":"{email}"}}}` | `id` → `itsm_user_id` (string)
`email_id` → `external_id` | *** ## Field Descriptions ### channel_id_info Fields | Field | Description | Format Examples | | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- | | `integration_id` | Your connector ID from Setup | `"msteams"`, `"slack"`, `"msteams_gcch"` | | `user_channel_id` | User ID in chat platform | Teams: `"28:{app_id}"`
Slack: `"{user_id}:{team_id}"`
Web Chat: `"email@company.com"` | ### user_itsm_id_info Fields | Field | Description | Format Examples | | -------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `integration_id` | Your connector ID from Setup | `"snow"`, `"jira_service_desk"`, `"salesforce"`, `"freshservice"`, `"manageengine"` | | `itsm_user_id` | User ID in ITSM system | ServiceNow: 32-char hex
Jira: `accountId`
Salesforce: 18-char
FreshService: numeric
ManageEngine: string | | `external_id` | Username or email | Varies by system | | `first_name`, `last_name`, `full_name` | Name fields | Parse from API response | *** ## Common Issues ### Cannot find service account in API * Try different search fields (email vs username vs UPN) * Verify account exists and is active * Check connector permissions * For ServiceNow, try: `sysparm_query=email={email}` or `sysparm_query=user_name={username}^active=true` ### MS Teams - Where to find Microsoft App ID * Go to **Setup → Manage Connectors → System Connectors** * Find your MS Teams connector * The Microsoft App ID is displayed in the connector configuration * Format for service account: `"28:{microsoft_app_id}"` * **If installed from MS App Store**: Use `"28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0"` ### Slack - Getting user_id and team_id * Use API Playground with your Slack connector * Call `/api/auth.test` endpoint * Response includes both `user_id` (starts with `U`) and `team` (team_id, starts with `T`) * Format: `"{user_id}:{team_id}"` (e.g., `"U01ABC123:T01ABC123"`) ### Jira displayName needs splitting * Parse `displayName` (e.g., "Moveworks Bot") into first/last name * Example: `firstName = displayName.split(" ")[0]`, `lastName = displayName.split(" ").slice(1).join(" ")` ### Multiple users returned from ITSM search * Add `sysparm_limit=1` (ServiceNow) or use exact match filters * Use unique identifiers (email) instead of partial names *** ## Best Practices 1. **Test in API Playground first** - Verify response format before configuring 2. **Use descriptive integration_ids** - For multi-tenant: `msteams_commercial`, `msteams_gcch`, `slack_main` 3. **Document multi-instance setups** - Add inline comments for each tenant/workspace 4. **Validate after configuring** - Setup → User Identity → View Users → search for service account *** ## Notes * **MS Teams format**: `user_channel_id` is `"28:{microsoft_app_id}"` from connector settings, or `"28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0"` if installed from MS App Store * **Slack format**: `user_channel_id` is `"{user_id}:{team_id}"` from `/api/auth.test` (e.g., `"U01ABC123:T01ABC123"`) * **Web Chat format**: `user_channel_id` is the service account email address * **ITSM ID formats**: ServiceNow (32-char hex), Jira (accountId), Salesforce (18-char), FreshService (numeric), ManageEngine (string) *** **Document Version:** 4.0 **Last Updated:** 2025-01-21