> This page is for Assistant Platform. > 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. # Lab #4: User Identity & Service Account Setup > **Info** > > ## Overview > > * **Learning Objectives:** Use a connected system to build the Moveworks user roster, configure the account that represents the Moveworks AI Assistant, and give employees access to Moveworks. > * **Estimated Time:** 45 minutes active | Up to 4 hours total (user ingestion runs after configuration) > * **Prerequisites:** > * [Lab #3](/ai-assistant/getting-started/labs/moveworks-setup/lab-3-connectors-api-playground) complete (`snow` connector configured and tested) > * The `machine_admin` integration account's email and `sys_id` (saved in [Lab #2: ServiceNow Setup](/ai-assistant/getting-started/labs/moveworks-setup/lab-2-servicenow-setup)) --- ### Key Concepts The user roster is the core of Moveworks identity. It determines who can interact with the Moveworks AI Assistant and what data belongs to them. Key components include: * **Source Connectors:** The primary systems (usually an ITSM or IDAM) from which Moveworks pulls raw employee data to build the user roster. * **Filters:** API query strings that narrow the records pulled from a source (e.g., only active users). * **Processors:** Automated functions that clean or "resolve" data during ingestion, such as transforming a manager's `sys_id` into a clickable name or calculating local time zones. * **Source Mapping (DSL Editor):** A per-attribute editor where you define exactly which source field maps to each Moveworks profile attribute, with the ability to test the mapping against a real user before saving. * **Joining Keys:** The unique identifier used to match a user across sources (e.g., email address). * **Bot Access Rule:** A global logic gate (often set to `TRUE` or controlled via DSL) that determines if a user is permitted to interact with the AI Assistant. **Relevant Documentation:** * [Moveworks Help: User Identity Overview](/platform-management/user-identity) * [Moveworks Help: Configuring User Ingestion](/platform-management/moveworks-setup/identity-configuration#steps-to-configure-user-identity) * [Moveworks Help: Configuring the Service Account](/platform-management/user-identity/service-account-configuration-guide) * [Moveworks Help: User Data Object](/api-reference/configuration-languages/data-dictionary#user) --- ## 🛠️ 1: Walkthrough ### 1.1: Configure User Identity The Identity Configuration is a 5-step wizard: **Select sources → Configure source mapping → Override field mapping → Set Joining Keys → Test with user**. #### Step 1: Select Sources 1. In **Moveworks Setup**, enter `identity` into the search bar and navigate to **User Identity > Identity Configuration**. Select `snow` as your primary source connector. ![](/_fern-files/_img/fe307c7883f9ab438764b18b0a680c84f2faa13ab06d2b35f66f3fb28658fb87.webp) 2. Click **Test** to confirm the connector is reachable. ![](/_fern-files/_img/05a05d0cd424b2713dd05aa239f8dbe5798449c043b566770bb72837a3624eec.webp) 3. After you see **Connector tested successfully**, click **Next: Configure Source Mapping** at the bottom right. > **Note** > > Secondary sources (for example, an HRIS or IDP) can be added under **Add secondary sources**. For this lab we are using `snow` as the single source of truth, so leave this empty. ![](/_fern-files/_img/e64f71759f015bd59918ad78a2a4a226ea680013ebeff713143fba87d92f2d8c.webp) #### Step 2: Configure Source Mapping 1. On the **Configure source mapping** step, locate your `snow` source row and click the **person icon** to the right. ![](/_fern-files/_img/dc3a8e424996429a7bcf95e57f6cfc55ac634beca48a9a1f0a030e9d9f71d7f6.webp) The person icon opens a **View Sample** dialog that shows real users returned by the source system. Use it to confirm your connector is reaching ServiceNow and pulling records before you continue configuring the mapping. > **Error** > > If users are **not** returned, go back to your connector and verify that your credentials were entered properly. ![](/_fern-files/_img/a2c90f77ea945f86112869dd5eea30060d37bbc2c449e02291aebd0781480e8e.webp) 2. Close the sample dialog, then click the **filter icon** next to your `snow` source to open the **Edit: snow** dialog. ![](/_fern-files/_img/c8f45c069a7477bc4c7388a6c976059d34468e6e7496031b13b232fc23657fbb.webp) 3. On the **Filters** tab, click **Add+** and set the **API Query String** to `active=true`. This ensures Moveworks only ingests active ServiceNow users. ![](/_fern-files/_img/e1f362497c429f748d70d4b1a7ac61bb1d298e60fe47807f265736d12f79d70e.webp) 4. Switch to the **Processors** tab, click **Add+**, select **User Timezone Processor**, and tick **Enable processor**. ![](/_fern-files/_img/1177516e672077af4ee45e5f7bfba40a94f706a249947dc478696363e2e9f8af.webp) 5. Click **Add+** again to add a second processor. Select **Unified Resolve Manager Processor** and tick **Enable processor**. This processor resolves each user's manager reference into a usable Moveworks profile attribute. > **Note** > > You can add more processors here (for example, **Password Expiry**) using **Add+** if your environment requires them. For this lab, the User Timezone and Unified Resolve Manager processors are enough to demonstrate the pattern. 6. With both processors configured, click **Confirm** to save your changes and close the **Edit: snow** dialog. ![](/_fern-files/_img/ebfc6a30967cc9f660eae092ff978f188cd3b88a3f8b6146f61d7c5ba1d5f8c4.webp) 7. After clicking **Confirm**, the dialog closes and you return to the source list. Click **View Attributes** on the `snow` row. ![](/_fern-files/_img/42b9b9c4fa885095b6ced8573abdf485cc33f08408b2e69517be714547e2315c.webp) 8. The row expands into the per-field mapping list, with a default for each attribute (for example, `department` maps from `department.display_value`). To inspect or override a mapping, click the **pencil icon** next to any attribute. This lab uses `department` as the example. ![](/_fern-files/_img/8df2b2b0b5ee6709452238039fb7eca47d130e5c2b565de33a08d1f55d908fd0.webp) 9. The **DSL editor** opens. Enter an email in **Test this mapping for a user** and click **Test Rule** to validate the mapping against a real ServiceNow record. When the result looks right, click **Save**. ![](/_fern-files/_img/f479a1fe4370c2b7838d55860b680f028a5e756db71693a86578f883f150609d.webp) ![](/_fern-files/_img/9c57578652cb64676dc7eccf6df094f84a4d948cd751fd5fe388ea6256c09991.webp) > **Note** > > **DSL Syntax Reference:** The default rule pattern is `$TRIM(IF THEN .display_value OR "" ELSE NULL)`. The **left-hand side** of each row is an attribute on the **Moveworks User Object**; the **right-hand side** is a **Moveworks DSL (Bender)** expression that reads from the source record. The [Optional Lab: Data Syntax Language (DSL)](/ai-assistant/getting-started/labs/moveworks-setup/optional-data-syntax-language-dsl) and [Optional Lab: Moveworks Bender](/ai-assistant/getting-started/labs/moveworks-setup/optional-moveworks-bender) cover the syntax in depth. 10. Review the full list of mappings, then click **Next: Override Field Mapping** at the bottom right. ![](/_fern-files/_img/030671c311fc843400fdb635ff55721cbc168e6b8b10c21b16e409185d8874a8.webp) #### Step 3: Override Field Mapping 1. The **Override field mapping** step is only used when you have secondary sources and want a specific attribute to come from a non-primary source. Since `snow` is our only source, leave this empty and click **Next: Set Joining Keys**. ![](/_fern-files/_img/97b10d51b38c4f777ec6b929ed854f498b7d70a98d18e1360c61ab8c180c24e8.webp) #### Step 4: Set Joining Keys 1. On the **Set Joining Keys** step, confirm the joining key for `snow` is set to the email mapping: `$TRIM(IF email THEN email.display_value OR "" ELSE NULL)`. Click **Next: Test With User**. > **Note** > > **Why it Matters** > > * **Identity Resolution:** Maps a chat user (e.g., Slack) to their backend records (e.g., ServiceNow). > * **Security:** Ensures sensitive actions like password resets are tied to a verified, authorized identity. > * **Data Integrity:** Prevents duplicate records during multi-source syncs. > > **Requirement:** A joining key must be **unique**, **immutable** (permanent), and **present** across all integrated systems. ![](/_fern-files/_img/12f899eeef7c6c4f6634b5a183b5cd1b27780760db23f5af22c0e33fdfa94068.webp) #### Step 5: Test With User 1. On the **Test with user** step, enter the email of a ServiceNow user (use your own lab user) and click **Show User Profile**. ![](/_fern-files/_img/58a9739d5803567597079721d05b9c1128c61f6d61daaae5c3593d67541206ba.webp) 2. Review the **Sample Results**. You should see attributes like `moveworks.first_name`, `moveworks.last_name`, `moveworks.email_addr`, `moveworks.role`, and `moveworks.department` resolve to real values. Attributes flagged `Null: Attribute not configured` or `Null: Primary source DSL evaluated to NULL` are expected for fields you have not customized in this lab. When satisfied, click **Save Configuration**. ![](/_fern-files/_img/33ee4f01c6852c8cb83baf9142ffb1bab34df4fcd8a736ffe902d4ccee78a380.webp) 3. Confirm the **Configuration passed test** dialog, then click **Proceed To Save**. ![](/_fern-files/_img/2b9253ad72e1649efb84e47d4236347567f50d7e795b63085d03a8845d2238de.webp) --- ### 1.2: Set Up the Moveworks Service Account > **Note** > > **In a live implementation,** you add an entry for each system where the Moveworks AI Assistant has a service account. See the [Moveworks Service Account Configuration Guide](/platform-management/user-identity/service-account-configuration-guide) for more information on what a multi-system Moveworks Service Account looks like. > **Error** > > **The Bot Account fields must exactly match the `machine_admin` integration account in ServiceNow.** Using mismatched values will cause Moveworks to fail to authenticate actions on behalf of users. Use the table below to confirm the correct values: > > | **Bot Account Field** | **Required Value** | > | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | **Email Address** | The email set on `machine_admin` in Lab #2: ServiceNow Setup | > | **Unique Record ID** | The same email address. This is the pre-hashed value of the joining key, so it must match the joining key value configured during user ingestion. Duplicate values are dropped. | > | **External ID** | The `machine_admin` `sys_id` from Lab #2: ServiceNow Setup, Section 1.4 | > | **ITSM User ID** | `machine_admin` | > | **Integration ID** | `snow`, or your connector name if you didn't use the default in Lab #3 | 1. Navigate to **User Identity > Advanced Settings > Bot Account** and enter the values from the table above. ![](/_fern-files/_img/339b61bb02229961b31bc280fed8cd2c5e7b57bbc10e1a228e8f44f8877dbe88.webp) *The screenshot shows example values (`admin@example.com`, `admin`). Enter the `machine_admin` values from your notes.* 2. Click **Submit**. --- ### 1.3: Set Up the Bot Access Rule > **Note** > > **Setting the Bot Access Rule to `TRUE` lets every ingested user interact with Moveworks**, as long as they can also reach Moveworks through one of these: > > * Integrated Chat Platform: > * Access to the Moveworks application in Slack, Teams, or another chat platform > * My Moveworks Access: > * A tile in their identity provider that opens the Moveworks on Web assistant > * Embedded AI Assistant: > * A Moveworks assistant embedded on a web page behind SSO, such as ServiceNow, SharePoint, or Freshservice 1. Navigate to **User Identity > Bot Access** and set the **Bot Access Rule** to `TRUE`. ![](/_fern-files/_img/7eacb3a7b7308312d33632feb4f3e5893ee3806fc0d515411f3c793355524c36.webp) --- ## ✅ 2: Verification & Next Steps 1. **Wait for Processing:** * Wait for the user ingestion cycle to complete. The user roster typically refreshes every 4 hours; lab environments may refresh more often. 2. **Confirm Completion:** * On the **User Identity > Imported Users** page, confirm that: * You can find yourself in the user roster * **Enabled Users** and **Bot Reachable Users** are greater than 0 * The page shows when the last ingestion cycle completed and when the next one is scheduled ![](/_fern-files/_img/b2bd1f2a3e630d12d1ce86602579eaafba110d5c1143df5d1f2647e0a3040d28.webp) > **Success** > > **Next:** [Lab #5: Install the Moveworks Update Sets](/ai-assistant/getting-started/labs/moveworks-setup/lab-5-moveworks-update-sets) --- ## 🪞 3: Reflecting on This Configuration Through this lab, you've learned the following: * How to configure Identity Sources within Moveworks using the 5-step Identity Configuration wizard * How to filter source records (e.g., `active=true`) and apply processors like User Timezone and Unified Resolve Manager * How to inspect and override individual attribute mappings using the DSL editor, including testing a rule against a real user * How joining keys link a user's identity across sources, and how to validate the end-to-end configuration with **Test With User** before saving * How to configure the Bot Account for the Moveworks integration account * How to enable access to the Moveworks AI Assistant * That Moveworks ingests users at a regular cadence, and you can see the currently ingested users + cadence in the `Imported Users` page --- ## ⚙️ 4: Configuration Details Use the table below to fill in the required fields accurately. | **Field Name** | **Action / Value to Enter** | | ------------------------------ | ------------------------------------------------------------------------------------------------------- | | **Primary Source Connector** | `snow` | | **Filters → API Query String** | `active=true` | | **Processors to Apply** | User Timezone Processor, Unified Resolve Manager Processor (add Password Expiry via **Add+** if needed) | | **Source Mapping** | Accept defaults; use the DSL editor to override and test individual attributes | | **Override Field Mapping** | None (single source) | | **Joining Key (snow)** | `$TRIM(IF email THEN email.display_value OR "" ELSE NULL)` | | **Bot Access Rule** | `TRUE` |