Service Account Configuration Guide

Complete guide for configuring Service Accounts in Moveworks Setup with channel_id_info and itsm_id_info for all systems.

Complete Configuration Example

{
  "email_addr": "[email protected]",
  "record_id": "[email protected]",
  "user_name": "moveworks-bot",
  "full_name": "Moveworks Bot",
  "role": "Virtual Assistant (Bot)",
  "department": "IT",
  "location": "Mountain View",
  "user_tags": ["BOT", "SERVICE_ACCOUNT"],

  "user_id_info": {
    "user_email": [
      "[email protected]",
      "[email protected]"
    ],

    "channel_id_info": [
      // ==========================================
      // MS Teams - Primary Tenant
      // API: GET /v1.0/users/{email}?$select=id,userPrincipalName,displayName,mail
      // Use: MS Graph connector in API Playground
      // ==========================================
      {
        "integration_id": "msteams",
        "user_channel_id": "28:12345678-1234-1234-1234-123456789abc",  // "28:" + response.id
        "instance_name": "company.onmicrosoft.com",                    // From userPrincipalName domain
        "external_id": "12345678-1234-1234-1234-123456789abc",        // response.id
        "bot_id": "12345678-1234-1234-1234-123456789abc"              // Azure Portal → Bot App ID
      },

      // ==========================================
      // MS Teams - Secondary Tenant (GCCH)
      // API: GET /v1.0/users/{email}?$select=id,userPrincipalName
      // Use: MS Graph GCCH connector in API Playground
      // ==========================================
      {
        "integration_id": "msteams_gcch",
        "user_channel_id": "28:87654321-4321-4321-4321-cba987654321",
        "instance_name": "company.onmicrosoft.us",
        "external_id": "87654321-4321-4321-4321-cba987654321",
        "bot_id": "87654321-4321-4321-4321-cba987654321"
      },

      // ==========================================
      // Slack - Primary Workspace
      // API: GET /api/users.info?user={user_id}
      // Use: Slack connector in API Playground
      // Alternative: /api/auth.test (for bot's own info)
      // ==========================================
      {
        "integration_id": "slack",
        "user_channel_id": "U01ABC123XYZ",      // response.user.id
        "instance_name": "company-workspace",    // Workspace name or team_id
        "external_id": "U01ABC123XYZ",          // response.user.id
        "bot_id": "B01ABC123XYZ"                // response.user.profile.bot_id
      },

      // ==========================================
      // Slack - Secondary Workspace
      // API: GET /api/users.info?user={user_id}
      // Use: Slack subsidiary connector in API Playground
      // ==========================================
      {
        "integration_id": "slack_subsidiary",
        "user_channel_id": "U02DEF456ABC",
        "instance_name": "subsidiary-workspace",
        "external_id": "U02DEF456ABC",
        "bot_id": "B02DEF456ABC"
      },

      // ==========================================
      // Web Chat
      // Note: No API call needed, configure in Setup
      // ==========================================
      {
        "integration_id": "movewebchat",
        "user_channel_id": "webchat_service_account",
        "instance_name": "company_web",
        "external_id": "webchat_service_account"
      }
    ],

    "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",   // response.result[0].sys_id
        "external_id": "moveworks.bot",                        // response.result[0].user_name
        "first_name": "Moveworks",                             // response.result[0].first_name
        "last_name": "Bot",                                    // response.result[0].last_name
        "full_name": "Moveworks Bot"                           // response.result[0].name
      },

      // ==========================================
      // 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",          // response[0].accountId
        "external_id": "[email protected]",           // response[0].emailAddress
        "first_name": "Moveworks",                            // Extract from displayName
        "last_name": "Bot",                                   // Extract from displayName
        "full_name": "Moveworks Bot"                          // response[0].displayName
      },

      // ==========================================
      // 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",                 // response.records[0].Id
        "external_id": "[email protected]",           // response.records[0].Username
        "first_name": "Moveworks",                            // response.records[0].FirstName
        "last_name": "Bot",                                   // response.records[0].LastName
        "full_name": "Moveworks Bot"                          // response.records[0].Name
      }
    ],

    "user_idm_id_info": [
      // ==========================================
      // Okta
      // API: GET /api/v1/users?search=profile.email eq "{email}"
      // Use: Okta connector in API Playground
      // Alternative: filter=profile.login eq "{username}"
      // ==========================================
      {
        "integration_id": "okta",
        "idm_user_id": "00u1a2b3c4d5e6f7g8h9",               // response[0].id
        "external_id": "[email protected]",           // response[0].profile.email
        "login_type": "OKTA"
      },

      // ==========================================
      // Azure AD
      // API: GET /v1.0/users?$filter=userPrincipalName eq '{upn}'&$select=id,userPrincipalName,displayName,mail
      // Use: MS Graph connector in API Playground
      // Alternative filter: $filter=mail eq '{email}'
      // ==========================================
      {
        "integration_id": "azure_ad",
        "idm_user_id": "12345678-1234-1234-1234-123456789abc", // response.value[0].id
        "external_id": "[email protected]", // response.value[0].userPrincipalName
        "login_type": "AZURE_AD"
      },

      // ==========================================
      // Google Workspace
      // API: GET /admin/directory/v1/users?customer=my_customer&query=email:{email}&projection=full
      // Use: Google Workspace connector in API Playground
      // Alternative: /admin/directory/v1/users/{email}
      // ==========================================
      {
        "integration_id": "google_workspace",
        "idm_user_id": "108123456789012345678",               // response.users[0].id
        "external_id": "[email protected]",           // response.users[0].primaryEmail
        "login_type": "GOOGLE"
      }
    ]
  }
}

How to Use API Playground

Navigate to Setup → Manage Connectors → System Connectors
Find the connector for your system (e.g., "MS Graph", "ServiceNow", "Slack")
Click "Test in API Playground"
Enter the API endpoint and parameters from the configuration example above
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	Endpoint	Search By	Response Field → Config Field
MS Teams	`/v1.0/users/{email}`	Email or UPN	`id` → `external_id` and in `user_channel_id` as `"28:{id}"` Get `bot_id` from Azure Portal → Bot Services → Microsoft App ID
Slack	`/api/users.info?user={user_id}` `/api/auth.test` (bot info)	User ID	`user.id` → `user_channel_id` and `external_id` `user.profile.bot_id` → `bot_id`
Web Chat	Configure in Setup	N/A	Use custom values (no API lookup needed)

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`

Identity Management Systems

System	Endpoint	Search Parameter	Response Field → Config Field
Okta	`/api/v1/users`	`search=profile.email eq "{email}"`	`id` → `idm_user_id` (00u...) `profile.email` → `external_id` Set `login_type: "OKTA"`
Azure AD	`/v1.0/users`	`$filter=userPrincipalName eq '{upn}'` `$select=id,userPrincipalName,displayName,mail`	`id` → `idm_user_id` (GUID) `userPrincipalName` → `external_id` Set `login_type: "AZURE_AD"`
Google Workspace	`/admin/directory/v1/users`	`customer=my_customer` `query=email:{email}` `projection=full`	`id` → `idm_user_id` (numeric) `primaryEmail` → `external_id` Set `login_type: "GOOGLE"`

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:{guid}"` Slack: `"U01ABC123XYZ"`
`instance_name`	Tenant/workspace identifier	Teams: `"company.onmicrosoft.com"` Slack: workspace name
`external_id`	Platform user ID	Teams: GUID without `"28:"` prefix Slack: same as `user_channel_id`
`bot_id`	Bot application ID	Teams: Azure App ID (GUID) Slack: `"B01ABC123XYZ"`

user_itsm_id_info Fields

Field	Description	Format Examples
`integration_id`	Your connector ID from Setup	`"snow"`, `"jira_service_desk"`, `"salesforce"`
`itsm_user_id`	User ID in ITSM system	ServiceNow: 32-char hex Jira: `accountId` Salesforce: 18-char
`external_id`	Username or email	Varies by system
`first_name`, `last_name`, `full_name`	Name fields	Parse from API response

user_idm_id_info Fields

Field	Description	Format Examples
`integration_id`	Your connector ID from Setup	`"okta"`, `"azure_ad"`, `"google_workspace"`
`idm_user_id`	User ID in IdM system	Okta: `"00u..."` Azure: GUID Google: numeric
`external_id`	Email or UPN	Varies by system
`login_type`	Authentication type	`"OKTA"`, `"AZURE_AD"`, `"GOOGLE"`

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 bot_id not in API response

bot_id is NOT from /v1.0/users endpoint
Get from Azure Portal → Bot Services → Configuration → Microsoft App ID

Slack bot_id missing

Use /api/auth.test with bot token to get bot_id
For user bots, check user.profile.bot_id in /api/users.info response

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

Add sysparm_limit=1 (ServiceNow) or use exact match filters
Use unique identifiers (email) instead of partial names

Best Practices

Test in API Playground first - Verify response format before configuring
Use descriptive integration_ids - For multi-tenant: msteams_commercial, msteams_gcch, slack_main
Keep external_id consistent - Use email for ITSM/IdM, platform ID for chat systems
Document multi-instance setups - Add inline comments for each tenant/workspace
Validate after configuring - Setup → User Identity → View Users → search for service account

Notes

MS Teams format: user_channel_id is "28:{user_id}", bot_id from Azure Portal
Slack IDs: User ID (U...) ≠ Bot ID (B...) - both required
System ID formats: ServiceNow (32-char hex), Jira (accountId), Salesforce (18-char), Okta (00u...)

Updated 3 minutes ago