> 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 full documentation content, see https://docs.moveworks.com/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server. # Bot Account and Manual User Management # Overview The **Bot Account** and **Manual User Management** pages let admins configure user identities that are not provided by a primary source system. They live under **User Identity > Advanced Configurations** in Moveworks Setup. * **Bot Account** — the single service account that represents Moveworks itself across your chat and ITSM systems. Required for the assistant to send messages, file tickets, and act on behalf of the bot identity. * **Manual User Management** — admin-managed list of users that are added directly through Setup. These users are created with the same attributes as imported users and appear in your **Imported Users** view alongside source-ingested records. Both pages write to the same identity store as imported users, so values you enter here flow through the standard identity pipeline. *** # Bot Account ## When to use this page Use the Bot Account page to declare the email, record, and ITSM identifiers Moveworks should use when acting as the bot. There is exactly one bot account per organization. If you are unsure whether your bot already has a service account configured, see the [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide) for the multi-system reference example. ## Fields | Field | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Email Address** | The canonical email for the bot account (for example, `moveworks-bot@yourcompany.com`). | | **Unique Record ID** | The value used to identify the bot across your systems — typically the same as the email address. This must match your organization's joining key so the record links correctly during ingestion. The value must be unique. | | **Full Name** | The display name shown for the bot in conversations and ticket activity. | | **ITSM ID Info** | One entry per ITSM system the bot operates in (ServiceNow, Jira, Zendesk, etc.). Each entry maps an integration to the bot's identifier in that system, which enables the Built-In Ticketing Plugin to act as the bot. | ## Configuring the bot account 1. Navigate to **User Identity > Advanced Configurations > Bot Account**. 2. Enter the **Email Address**, **Unique Record ID**, and **Full Name** for the bot. 3. Under **ITSM ID Info**, click **Add** and provide one entry for each ticketing system the bot operates in (see [Setting up ITSM ID Info](#setting-up-itsm-id-info) below). 4. Click **Submit**. ## Setting up ITSM ID Info ITSM ID Info is the part of the bot account that ties Moveworks to the bot's actual user record inside each ticketing system. Without it, the Built-In Ticketing Plugin cannot file, update, or close tickets on behalf of the bot — when an admin later configures an ITSM Provider, Moveworks looks up the bot's identifier here to resolve who the requests are coming from. Add **one entry per ticketing system** the bot needs to operate in. For each entry, fill in the following fields. ### Required fields | Field | What it must match | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration** | The integration ID of the ticketing connector you set up under **Manage Connectors > System Connectors** in Moveworks. Examples: `snow` (ServiceNow), `jira_service_desk` (Jira), `salesforce`, `freshservice`, `manageengine`, `zendesk`. This value links the entry to the right ITSM Provider — if it does not match an existing connector, ticketing plugins for that system will fail to find the bot. | | **External ID** | The bot's **user identifier in the ticketing system itself**. Moveworks reads this value to determine "who the bot is" inside that system, and it is what gets stamped onto the ITSM Provider configuration when an admin later sets one up. Use the value the ticketing system uses to identify the user — typically the username (ServiceNow `user_name`), the email address (Jira `emailAddress`, FreshService `primary_email`), or the system-issued user ID. | ### Recommended fields | Field | What it should match | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **ITSM User ID** | The internal record ID for the bot's user in the ticketing system. ServiceNow returns this as `sys_id` (32-character hex), Jira returns it as `accountId`, Salesforce as the 18-character user `Id`, FreshService and ManageEngine as numeric/string user `id`. This is used for direct record lookups; populate it whenever you have the value. | | **First Name**, **Last Name**, **Full Name** | The bot's name as stored in the ticketing system. These are used for display in ticket activity and should match what the ticketing system returns for the bot user. | ### Where each value comes from Pull the values for each ITSM directly from that system's user-lookup API. The exact endpoint and field mapping for the most common ticketing systems is documented in the [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide#api-quick-reference) under **API Quick Reference > ITSM Systems**. A summary: * **ServiceNow** — query `/api/now/table/sys_user` by `user_name`. Use `sys_id` as **ITSM User ID** and `user_name` as **External ID**. * **Jira** — query `/rest/api/3/user/search` by email. Use `accountId` as **ITSM User ID** and `emailAddress` as **External ID**. * **Salesforce** — query the User object via SOQL. Use the 18-character `Id` as **ITSM User ID** and `Username` as **External ID**. * **FreshService** — query `/api/v2/requesters` by `primary_email`. Use the numeric `id` as **ITSM User ID** and `primary_email` as **External ID**. * **ManageEngine** — query `/api/v3/users` by `email_id`. Use `id` as **ITSM User ID** and `email_id` as **External ID**. ### Validation checklist Before submitting, confirm for every ITSM ID Info entry: * The **Integration** value matches the integration ID of the connector for that ticketing system (case-sensitive). Mismatched values are the most common cause of "no bot service account found" errors when an admin later sets up an ITSM Provider. * The **External ID** is the value the ticketing system itself uses to identify the bot's user (usually the username or email shown in that system's UI for the bot account). * The bot user actually exists and is **active** in the ticketing system, with the permissions needed to create and update tickets. * If the bot operates in multiple ticketing systems, there is **one entry per system** — do not combine systems in a single entry. If you need a fully worked, end-to-end example covering chat platforms and every supported ITSM, see the [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide). *** # Manual User Management ## When to use this page Use Manual User Management to add users that are not present in your primary identity source — for example, contractors, partners, or service accounts that exist in chat or ITSM systems but are not in your HR or directory system. Users added here appear in **Imported Users** alongside source-ingested users. They participate in the same plugins, permissions, and access rules. ## The home page The home view lists every manually managed user. From here you can: * Click **Add User** to create a new entry (opens the **New Manual User** form). * Click an existing user to open the **Edit Manual User** form. * Submit changes to update the imported users record for that user. ## Fields on the New / Edit form The form is organized into three sections. ### Identity | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Email Address** | The user's primary email. | | **Unique Record ID** | The value used to identify the user across systems — typically the email address. This must match your organization's joining key. The value must be unique within the manual user list. | | **Full Name** | The user's full name as it should appear in the assistant. | ### User ID Info This section maps the user to their identifiers in connected systems. * **User Email** — additional email aliases the user is known by. * **Channel ID Info** — chat platform identifiers (Slack, Microsoft Teams, etc.) that allow the user to converse with the assistant. * **ITSM ID Info** — ticketing system identifiers, used when the user creates or is assigned to tickets. * **IDM ID Info** — identity provider identifiers (Okta, Azure AD, etc.) used for access skills. Add one entry per system the user is active in. ### Advanced settings Optional profile attributes that mirror what would be ingested from a directory source. Fill in the ones that apply to the user; leave the rest blank. | Field | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **User Tags** | Tags such as `BASIC_USER`, `VIP`, `TESTER`, or `SERVICE_ACCOUNT`. Tags drive bot access rules and analytics filters. See [How to Configure User Tags](/agent-studio/core-platform/user-identity/advance-configurations-identity#how-to-configure-user-tags-based-on-conditions). | | **Role** | The user's job title. | | **Department** | The user's department. | | **User Name** | The user's username, if different from the email. | | **First Name** / **Last Name** | The user's given and family name. | | **Location** | The user's primary work location. | | **Manager** / **Manager Email** | The manager reference and email used by approval flows and personalized responses. | | **Employee ID** | The organization-issued employee identifier. | | **Timezone** | The user's timezone (used for scheduling and notifications). | | **Cost Center Name** | The cost center the user belongs to. | | **Country Code** | The user's country. | | **Work Status** | One of `CONTINGENT`, `INTERN`, or `FULL_TIME`. | | **Division** | The user's division. | | **Region** | The user's region. | | **City** | The user's city. | | **Custom Attributes** | Free-form key/value pairs for any custom data your organization tracks on users. The attribute names must already be registered in **Custom Attributes** under **Analytics and Data**. | ## Adding a new manual user 1. Navigate to **User Identity > Advanced Configurations > Manual User Management**. 2. Click **Add User**. 3. Fill in **Email Address**, **Unique Record ID**, and **Full Name** at minimum. 4. Add entries under **User ID Info** for every system the user needs to be reachable in. 5. Optionally fill in any **Advanced settings** that apply. 6. Click **Submit**. The user appears in **Imported Users** after the next identity refresh. ## Editing or removing a manual user 1. Open **Manual User Management**. 2. Click the user you want to change. 3. Update the fields and click **Submit**, or remove the entry from the list view to delete the user. *** # FAQ ## How are manually managed users ingested? Bot Account and Manual User Management entries are ingested by the same User Identity pipeline that processes records from external identity sources — they are treated as another input during the merge step, then validated and loaded into the user store. **For organizations with at least one external identity source** (Workday, Okta, Active Directory, etc.): * Manual entries are folded in on the regular User Identity ingestion cycle (every 4 hours, alongside the rest of the [User Import Process](/service-management/core-platform/user-identity)). * For each manual entry, Moveworks looks for a source record whose joining key matches the entry's **Unique Record ID**. If found, the two are merged into a single Moveworks User. If no match exists, the manual entry becomes a standalone Moveworks User. **For organizations with no external identity source**: * A dedicated User Identity ingestion runs on a 30-minute schedule. The fetch / map / process source steps are skipped (since there is nothing to fetch), and the pipeline goes straight to the merge step using your Bot Account and Manual User Management entries as the only inputs. * After the merge, the same validators and load steps run, so manually added users land in **Imported Users** within \~30 minutes of submission. In both cases, manually added users go through the standard validators (duplicate detection, large data change protection) and load steps before they appear in **Imported Users**. ## What happens if I enter the wrong Unique Record ID? The behavior depends on what value you typed and what your organization uses as its joining key: * **The value does not match any source record's joining key.** The manual entry is loaded as a standalone Moveworks User on the next ingestion run. The same person may then appear twice in **Imported Users** — once from the connected source under their real joining key, and once from the manual entry under the value you typed. * **The value matches another user's joining key.** The manual entry merges into that user's record on the next ingestion run, overlaying fields with the values you entered. This is the most common cause of "wrong fields showing up" on a Moveworks User after a manual entry is added. * **The value is empty.** Submit is blocked at the form level — Unique Record ID is required. * **The value duplicates another entry in Manual User Management.** Submit is blocked — Unique Record IDs must be unique within the manual user list. To correct a wrong Unique Record ID, open the entry from the Manual User Management home view, edit the field, and submit. The next ingestion run rebuilds the merge with the corrected value; no manual cleanup is needed in the user store. Until the next ingestion run completes, **Imported Users** will still reflect the previous (incorrect) state. ## Does the Unique Record ID have to be an email address? No. The Unique Record ID is a free-form string — the only requirements are that it is non-empty and unique within the Manual User Management list. What it **should** match is your organization's configured joining key for the User Identity pipeline: * For most organizations the joining key is the user's primary **email address**, so using the email is correct. * Organizations that join on a different attribute should use that attribute instead. Common alternatives: * **Employee ID** (e.g., `E12345`) — used when an HR system is the primary source. * **User Principal Name (UPN)** (e.g., `jane.doe@corp.local`) — used when Active Directory or Azure AD is the primary source and the UPN differs from the email. * **Username** (e.g., a ServiceNow `user_name`) — used in ITSM-driven joins. * **Custom external IDs** issued by the primary source. If you are unsure which value your organization joins on, check the joining key configured under your primary identity source, or see the [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide) for a worked example. Setting the Unique Record ID to anything other than the joining key will prevent the manual entry from merging with the corresponding source record. *** # Tips * **Joining key** — the value you enter for **Unique Record ID** must match the joining key used by your primary identity source. If joining keys differ, the manually added user will not merge correctly with any matching source record. See [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide) for an end-to-end example. * **ITSM ID Info is required for ticketing** — if the bot or a manual user needs to act in a ticketing system, fill in the ITSM ID Info for that system. Without it, ticketing plugins cannot resolve the user. * **Tags drive access** — apply user tags such as `HAS_ACCESS_TO_BOT` or `TESTER` so the user is included or excluded from the right rules and dashboards. See [Bot Access Rules](/agent-studio/core-platform/user-identity/bot-access-rules). # Related guides * [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide) * [How To Guides for User Identity Plugin](/agent-studio/core-platform/user-identity/advance-configurations-identity) * [Ingested Users](/agent-studio/core-platform/user-identity/control-centre-identity) * [User Attribute Reference](/agent-studio/core-platform/user-identity/user-attribute-reference)