> This page is for Platform Management. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.moveworks.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # Service Account Configuration Guide ## Overview A **Bot Account** is required for Moveworks to function. Without one, the user roster cannot be ingested and the assistant cannot perform automated actions on behalf of any system. **Purpose:** * **User Roster Ingestion** — A Bot Account must exist for the User Identity Flow to execute. * **Automated Actions** — Lets the assistant create tickets, submit requests, and act in connected systems. * **System Integration** — Maps the bot's identity across chat platforms (Teams/Slack), ITSM systems (ServiceNow/Jira), and identity providers (Okta/Azure AD). In addition to the Bot Account, you can use **Manual User Management** to add and edit individual users (for example, contractors or service accounts that aren't in your standard roster) directly from Setup. --- ## What changed The previous experience asked you to author a single JSON document that combined the bot, manual users, and all of their identity mappings. That has been replaced with two dedicated, form-based pages in the **Advanced Configuration Editor**: | Page | What it configures | How many records | | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------- | | **Bot Account** | The single Moveworks bot identity used for automated actions and ITSM integrations | One per org | | **Manual User Management** | Individual users added by hand (contractors, service accounts, etc.) that should appear in the imported users view | Many | You no longer hand-edit JSON. Each page renders a structured form with grouped sections, validation, and inline help. The `record_id` you choose for any account must be unique and must not collide with a record from your standard user roster — duplicates are dropped on ingest. --- ## Where to configure 1. Open **Moveworks Setup → User Identity → Advanced Configurations**. 2. Choose: * **Bot Account** — to create or edit the single Moveworks bot identity. * **Manual User Management** — to add, edit, or remove individual users. 3. Fill in the form and click **Submit**. Submissions are recorded in Config Change History. --- ## Bot Account The Bot Account form has two sections. ### Identity (required) | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Email Address** | Primary email address for the bot (for example, `moveworks-bot@company.com`). | | **Unique Record ID** | A unique identifier for this record. An email address is a good default. Must not duplicate an existing roster record. | | **Full Name** | Display name for the bot (for example, `Moveworks Bot`). | ### ITSM ID Info Add one entry per ITSM system the bot needs to act in. Each entry maps the bot's identity in that system so the assistant can create tickets, submit requests, and look up records. | Field | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Connector** | Select the connector for the ITSM system from the dropdown. The list is populated from the System Connectors you set up under **Setup → Manage Connectors**, so you pick an existing connector instead of typing its ID. | | **ITSM User ID** | The bot's user record ID in the ITSM system. | | **External ID** | The bot's username or email in the ITSM system. | | **First Name / Last Name / Full Name** | Name fields as they appear in the ITSM system. | > **Tip:** Use **API Playground** on each system connector to look up the bot's IDs before adding the entry. > **Note** > > **ServiceNow:** the **ITSM User ID** is the ServiceNow **username** (the `user_name` value, e.g. `Red_MoveWorks`), and the **External ID** is the ServiceNow **sys ID** (the 32-character `sys_id` value). --- ## Manual User Management Use this page to add, edit, or remove a single user. Users created here appear in the imported users view alongside roster-ingested users. ### Identity (required) | Field | Description | | -------------------- | --------------------------------------------------------------------------------------------- | | **Email Address** | The user's primary email. | | **Unique Record ID** | Unique identifier for the record. Must not duplicate a record from your standard user roster. | | **Full Name** | The user's display name. | ### User ID Info Add one or more entries to map the user across the systems they should be reachable in. #### User Emails A list of additional email addresses this user is known by. Used for identity resolution across systems. #### Channel ID Info — chat platforms | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------------------- | | **Integration ID** | Chat connector ID (for example, `msteams`, `msteams_gcch`, `slack`, `slack_subsidiary`, `movewebchat`). | | **User Channel ID** | The user's ID in the chat platform. See [chat formats](#channel-id-formats) below. | | **Instance Name** | Optional. Used when the same connector type is configured for multiple tenants or workspaces. | | **External ID** | Optional. The user's external identifier in the chat platform. | | **Bot ID** | Optional. The bot identifier for the channel, if applicable. | #### ITSM ID Info — ticketing systems Same fields as the **Bot Account → ITSM ID Info** section above. Add one entry per ITSM system. #### IDM ID Info — identity providers | Field | Description | | ------------------ | --------------------------------------------------- | | **Integration ID** | IDM connector ID (for example, `okta`, `azure_ad`). | | **IDM User ID** | The user's ID in the identity provider. | | **External ID** | Username or email in the identity provider. | | **Login Type** | Optional login type for the IDM record. | ### Advanced Settings (optional) The advanced section lets you set roster-style attributes when this user shouldn't be merged from an upstream system. | Field | Notes | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **User Tags** | Tags applied to this user. Common values include `BOT`, `VIP`, `IT_AGENT`, `KNOWLEDGE_WORKER`, `FIELD_AGENT`, `SERVICE_ACCOUNT`, `CALL_CENTER`, `EXECUTIVE`, `DIRECTOR`, `BASIC_USER`, `TESTER`. | | **Role / Department / User Name** | Job role, department, and login/username. | | **First Name / Last Name** | Standard name fields. | | **Location / Country Code / Region / City / Division** | Location attributes. | | **Manager / Manager Email** | Manager pointer. Set both fields when known. | | **Employee ID** | Employee identifier from your HRIS, if applicable. | | **Timezone** | IANA timezone (for example, `America/Los_Angeles`). | | **Cost Center Name** | Cost center this user rolls up to. | | **Work Status** | One of `FULL_TIME`, `CONTINGENT`, or `INTERN`. | | **Custom Attributes** | Free-form key/value map for org-specific attributes. | --- ## Channel ID formats | Platform | Format | How to obtain | | ------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **MS Teams** | `28:{microsoft_app_id}` | Get the Microsoft App ID from the MS Teams connector in Setup. **If installed from MS App Store**, use `28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0`. | | **MS Teams (GCCH)** | `28:{microsoft_app_id}` | Use the App ID from your GCCH-tenant MS Teams connector. Set **Integration ID** to `msteams_gcch`. | | **Slack** | `{user_id}:{team_id}` | Call `/api/auth.test` in API Playground using the Slack connector. The response contains `user_id` (starts with `U`) and `team` (starts with `T`). | | **Web Chat** | `email@company.com` | Use the user's email address. | --- ## ITSM lookup quick reference Use **API Playground** on the matching system connector to look up `itsm_user_id` and other fields before adding the ITSM entry. | System | Endpoint | Search parameter | Response field → Form 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` | `user_name` → **ITSM User ID** `sys_id` → **External ID** (32-char hex) | | **Jira Service Management** | `/rest/api/3/user/search?query={email}` | Email or username | `accountId` → **ITSM User ID** `emailAddress` → **External ID** Split `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** `email_id` → **External ID** | ### How to use API Playground 1. Open **Setup → Manage Connectors → System Connectors**. 2. Find the connector for your system (for example, MS Teams, Slack, ServiceNow). 3. Click **Test in API Playground**. 4. Enter the endpoint and parameters from the table above. 5. Copy the relevant response values into the form. API Playground handles authentication automatically through your configured connector. --- ## Common issues ### Cannot find the account in the ITSM API * Try alternate search fields (email vs. username vs. UPN). * Verify the account exists and is active. * Check that the connector has read permissions on the user table. * For ServiceNow, try `sysparm_query=email={email}` or `sysparm_query=user_name={username}^active=true`. ### MS Teams — where is the Microsoft App ID? * Go to **Setup → Manage Connectors → System Connectors** and open the MS Teams connector — the App ID is shown in the configuration. * Format the channel ID as `28:{microsoft_app_id}`. * If installed from the MS App Store, use `28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0`. ### Slack — getting the user ID and team ID * Open API Playground on your Slack connector and call `/api/auth.test`. * The response contains `user_id` (starts with `U`) and `team` (starts with `T`). * Combine them as `{user_id}:{team_id}` (for example, `U01ABC123:T01ABC123`). ### Jira `displayName` needs splitting * Split `displayName` (for example, `Moveworks Bot`) into **First Name** and **Last Name**. * Example: first name = the first token, last name = the rest joined by a space. ### Multiple users returned from an ITSM search * Add `sysparm_limit=1` (ServiceNow) or use exact-match filters. * Prefer unique identifiers (email, username) over partial names. ### Record dropped on ingest * The **Unique Record ID** must not collide with an existing record in your standard user roster. * Use a value the upstream roster will not generate (for example, `moveworks-bot@company.com` for the Bot Account, or a contractor-prefixed email for manual users). --- ## Best practices 1. **Look up IDs in API Playground first** — verify response shape before saving the form. 2. **Use descriptive Integration IDs for multi-tenant setups** — for example, `msteams_commercial`, `msteams_gcch`, `slack_main`, `slack_subsidiary`. 3. **Set both Manager and Manager Email** when adding manual users so org-chart features work end-to-end. 4. **Validate after configuring** — open **Setup → User Identity → View Users** and search for the account. --- ## Notes * MS Teams **User Channel ID** is `28:{microsoft_app_id}` from the connector, or `28:b8ec4e1a-e05a-49d0-ba3a-05119b8b62c0` if the bot was installed from the MS App Store. * Slack **User Channel ID** is `{user_id}:{team_id}` from `/api/auth.test`. * Web Chat **User Channel ID** is the account's email address. * ITSM ID formats vary: ServiceNow (32-char hex), Jira (`accountId`), Salesforce (18-char), FreshService (numeric), ManageEngine (string). --- **Document Version:** 5.0 **Last Updated:** 2026-04-22