***

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<br />**If installed from MS App Store**: Use fixed value | `"28:{microsoft_app_id}"`<br />App Store: `"28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0"` |
| **Slack**    | API: `/api/auth.test`<br />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}`<br />`sysparm_fields=sys_id,user_name,email,first_name,last_name,name`<br />`sysparm_limit=1` | `sys_id` → `itsm_user_id` (32-char hex)<br />`user_name` → `external_id`                                    |
| **Jira**         | `/rest/api/3/user/search?query={email}` | Email or username                                                                                                                  | `accountId` → `itsm_user_id`<br />`emailAddress` → `external_id`<br />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)<br />`Username` → `external_id`                                             |
| **FreshService** | `/api/v2/requesters`                    | `query="primary_email:'{email}'"`                                                                                                  | `id` → `itsm_user_id` (numeric)<br />`primary_email` → `external_id`                                        |
| **ManageEngine** | `/api/v3/users`                         | `input_data={"list_info":{"search_criteria":{"field":"email_id","value":"{email}"}}}`                                              | `id` → `itsm_user_id` (string)<br />`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}"`<br />Slack: `"{user_id}:{team_id}"`<br />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<br />Jira: `accountId`<br />Salesforce: 18-char<br />FreshService: numeric<br />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