Core PlatformUser Identity

Service Account Configuration Guide

Configure the Bot Account and manually-managed users in Moveworks Setup using the new Advanced Configuration Editor.

View as Markdown

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:

PageWhat it configuresHow many records
Bot AccountThe single Moveworks bot identity used for automated actions and ITSM integrationsOne per org
Manual User ManagementIndividual users added by hand (contractors, service accounts, etc.) that should appear in the imported users viewMany

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)

FieldDescription
Email AddressPrimary email address for the bot (for example, moveworks-bot@company.com).
Unique Record IDA unique identifier for this record. An email address is a good default. Must not duplicate an existing roster record.
Full NameDisplay 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.

FieldDescription
Integration IDThe connector ID for the ITSM system (for example, snow, jira_service_desk, salesforce, freshservice, manageengine). Find it under Setup → Manage Connectors → System Connectors.
ITSM User IDThe bot’s user record ID in the ITSM system.
External IDThe bot’s username or email in the ITSM system.
First Name / Last Name / Full NameName 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.

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)

FieldDescription
Email AddressThe user’s primary email.
Unique Record IDUnique identifier for the record. Must not duplicate a record from your standard user roster.
Full NameThe 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

FieldDescription
Integration IDChat connector ID (for example, msteams, msteams_gcch, slack, slack_subsidiary, movewebchat).
User Channel IDThe user’s ID in the chat platform. See chat formats below.
Instance NameOptional. Used when the same connector type is configured for multiple tenants or workspaces.
External IDOptional. The user’s external identifier in the chat platform.
Bot IDOptional. 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

FieldDescription
Integration IDIDM connector ID (for example, okta, azure_ad).
IDM User IDThe user’s ID in the identity provider.
External IDUsername or email in the identity provider.
Login TypeOptional 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.

FieldNotes
User TagsTags 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 NameJob role, department, and login/username.
First Name / Last NameStandard name fields.
Location / Country Code / Region / City / DivisionLocation attributes.
Manager / Manager EmailManager pointer. Set both fields when known.
Employee IDEmployee identifier from your HRIS, if applicable.
TimezoneIANA timezone (for example, America/Los_Angeles).
Cost Center NameCost center this user rolls up to.
Work StatusOne of FULL_TIME, CONTINGENT, or INTERN.
Custom AttributesFree-form key/value map for org-specific attributes.

Channel ID formats

PlatformFormatHow to obtain
MS Teams28:{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 Chatemail@company.comUse 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.

SystemEndpointSearch parameterResponse field → Form field
ServiceNow/api/now/table/sys_usersysparm_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 Service Management/rest/api/3/user/search?query={email}Email or usernameaccountId → ITSM User ID
emailAddress → External ID
Split displayName → First / Last Name
Salesforce/services/data/v58.0/queryq=SELECT Id,Username,Email,FirstName,LastName,Name FROM User WHERE Username='{username}'Id → ITSM User ID (18-char)
Username → External ID
FreshService/api/v2/requestersquery="primary_email:'{email}'"id → ITSM User ID (numeric)
primary_email → External ID
ManageEngine/api/v3/usersinput_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.
  • 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