Service Account Configuration Guide

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

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.

{
  // ==========================================
  // Primary email address - the canonical email for this service account
  // ==========================================
  "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"],

  "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": [
      "[email protected]",
      "[email protected]"
    ],

    "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": "[email protected]"
      }
    ],

    "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "first_name": "Moveworks",
        "last_name": "Bot",
        "full_name": "Moveworks Bot"
      }
    ]
  }
}

How to Use API Playground

Navigate to Setup → Manage Connectors → System Connectors
Find the connector for your system (e.g., "MS Teams", "Slack", "ServiceNow")
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	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 protected]"`

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 protected]"`

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

Test in API Playground first - Verify response format before configuring
Use descriptive integration_ids - For multi-tenant: msteams_commercial, msteams_gcch, slack_main
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:{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

Updated 20 days ago