> 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 #2: User Identity & Service Account Setup ## Overview * **Learning Objectives:** Learn how to leverage connected systems to build a Moveworks User Roster. Understand how to configure the account representing the Moveworks AI Assistant, and give end-users access to Moveworks. * **Estimated Time:** 45 minutes active | Up to 4 hours total (user ingestion runs after configuration) * **Prerequisites:** * [Lab 1](/ai-assistant/getting-started/labs/moveworks-setup/lab-1-connectors-api-playground-4229833d14141f6f) complete (snow connector configured and tested) * The `sys_id` of the ServiceNow admin account (copied during Lab 0, Step 1.3) *** ### Key Concepts The User Roster is the "brain" of Moveworks identity, determining 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](https://help.moveworks.com/service-management/core-platform/user-identity) * [Moveworks Help: Configuring User Ingestion](https://help.moveworks.com/service-management/core-platform/user-identity/mw-setup-identity#overview) * [Moveworks Help: Configuring the Service Account](https://help.moveworks.com/service-management/core-platform/user-identity/service-account-configuration-guide) * [Moveworks Help: User Data Object](https://help.moveworks.com/service-management/core-platform/moveworks-data-objects#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. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/fe307c7883f9ab438764b18b0a680c84f2faa13ab06d2b35f66f3fb28658fb87/docs/assets/images/setup-labs/lab2_new_identity_1.png) 2. Click **`Test`** to confirm the connector is reachable. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/05a05d0cd424b2713dd05aa239f8dbe5798449c043b566770bb72837a3624eec/docs/assets/images/setup-labs/lab2_new_identity_2.png) 3. After you see **`Connector tested successfully`**, click **`Next: Configure Source Mapping`** at the bottom right. 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. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/e64f71759f015bd59918ad78a2a4a226ea680013ebeff713143fba87d92f2d8c/docs/assets/images/setup-labs/lab2_new_identity_3.png) #### 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. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/dc3a8e424996429a7bcf95e57f6cfc55ac634beca48a9a1f0a030e9d9f71d7f6/docs/assets/images/setup-labs/lab2_new_identity_4_sample_users.png) 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. If users are **not** returned, go back to your connector and verify that your credentials were entered properly. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/a2c90f77ea945f86112869dd5eea30060d37bbc2c449e02291aebd0781480e8e/docs/assets/images/setup-labs/lab2_new_identity_6.png) 2. Close the sample dialog, then click the **filter icon** next to your `snow` source to open the **Edit: snow** dialog. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/c8f45c069a7477bc4c7388a6c976059d34468e6e7496031b13b232fc23657fbb/docs/assets/images/setup-labs/lab2_new_identity_7.png) 3. On the **Filters** tab, click **`Add+`** and set the **API Query String** to `active=true`. This ensures Moveworks only ingests active ServiceNow users. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/e1f362497c429f748d70d4b1a7ac61bb1d298e60fe47807f265736d12f79d70e/docs/assets/images/setup-labs/lab2_new_identity_8.png) 4. Switch to the **Processors** tab, click **`Add+`**, select **`User Timezone Processor`**, and tick **`Enable processor`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/1177516e672077af4ee45e5f7bfba40a94f706a249947dc478696363e2e9f8af/docs/assets/images/setup-labs/lab2_new_identity_9.png) 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. 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. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/ebfc6a30967cc9f660eae092ff978f188cd3b88a3f8b6146f61d7c5ba1d5f8c4/docs/assets/images/setup-labs/lab2_user_identity_10.png) 7. After clicking **`Confirm`**, the dialog closes and you return to the source list. Click **`View Attributes`** on the `snow` row. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/42b9b9c4fa885095b6ced8573abdf485cc33f08408b2e69517be714547e2315c/docs/assets/images/setup-labs/lab2_user_identity_11.png) 8. The row expands into the per-field mapping list, with sensible defaults 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 — we'll use **`department`** as the worked example. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/8df2b2b0b5ee6709452238039fb7eca47d130e5c2b565de33a08d1f55d908fd0/docs/assets/images/setup-labs/lab2_new_identity_11.png) 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`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/f479a1fe4370c2b7838d55860b680f028a5e756db71693a86578f883f150609d/docs/assets/images/setup-labs/lab2_new_identity_12.png) ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/9c57578652cb64676dc7eccf6df094f84a4d948cd751fd5fe388ea6256c09991/docs/assets/images/setup-labs/lab2_new_identity_13.png) **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. Detailed instruction on Moveworks DSL syntax and logic will be covered in a subsequent laboratory session. 10. Review the full list of mappings, then click **`Next: Override Field Mapping`** at the bottom right. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/030671c311fc843400fdb635ff55721cbc168e6b8b10c21b16e409185d8874a8/docs/assets/images/setup-labs/lab2_new_identity_14.png) #### 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`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/97b10d51b38c4f777ec6b929ed854f498b7d70a98d18e1360c61ab8c180c24e8/docs/assets/images/setup-labs/lab2_new_identity_15.png) #### 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`**. **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. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/12f899eeef7c6c4f6634b5a183b5cd1b27780760db23f5af22c0e33fdfa94068/docs/assets/images/setup-labs/lab2_new_identity_16.png) #### Step 5: Test With User 1. On the **Test with user** step, enter the email of a ServiceNow user (use your own lab user, or the ServiceNow admin email) and click **`Show User Profile`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/58a9739d5803567597079721d05b9c1128c61f6d61daaae5c3593d67541206ba/docs/assets/images/setup-labs/lab2_new_identity_18.png) 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`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/33ee4f01c6852c8cb83baf9142ffb1bab34df4fcd8a736ffe902d4ccee78a380/docs/assets/images/setup-labs/lab2_new_identity_19.png) 3. Confirm the **Configuration passed test** dialog, then click **`Proceed To Save`**. ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/2b9253ad72e1649efb84e47d4236347567f50d7e795b63085d03a8845d2238de/docs/assets/images/setup-labs/lab2_new_identity_20.png) *** ### 1.2: Setup the Moveworks Service Account **Note:** When configuring this for a new implementation, we will add the relevant information for each integration that the Moveworks AI Assistant has a service account within. See the [Moveworks Service Account Configuration Guide](https://help.moveworks.com/docs/service-account-configuration-guide) for more information on what a multi-system Moveworks Service Account looks like. **The Bot Account fields must exactly match your ServiceNow admin account.** 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** | Email address of the ServiceNow admin account (e.g. `admin@example.com`) | | **Unique Record ID** | Same as the email address (e.g. `admin@example.com`). This is the pre-hashed value of the join key — it must match the joining key value configured during user ingestion. Duplicate values will be dropped. | | **External ID** | The `sys_id` of the admin user record in ServiceNow — copied in Lab 0, Step 1.3 | | **ITSM User ID** | The ServiceNow username — `admin` (unless you changed it) | | **Integration ID** | `snow` — or your custom connector name if you did not use the default in Lab 1 | 1. Navigate to the `Bot Account` page, and **add the corresponding information for the Moveworks Service Account user for each field** ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/339b61bb02229961b31bc280fed8cd2c5e7b57bbc10e1a228e8f44f8877dbe88/docs/assets/images/setup-labs/lab2_46df36dd-9609-4b52-b769-bcb6aa579f4f_new_service_account_ui.png) 2. After you enter your configuration, **`Submit`** your changes *** ### 1.3: Set up Bot Access Rule **Note:** Setting the `Bot Access Rule` to `TRUE` will give all users who are ingested into Moveworks access to interact with Moveworks, but they must also have access to Moveworks via one of the following methods: * Integrated Chat Platform: * Access to talk to the Moveworks application in Slack, Teams, etc * My Moveworks Access: * Ability to select a tile in their IDAM platform that allows them to interact with the Moveworks on Web Assistant * Embedded AI Assistant: * Access to a Moveworks Assistant that has been surfaced on a web page controlled by IDAM SSO. This includes platforms like ServiceNow, Sharepoint, FreshService, etc 1. Navigate to **`User Identity > Bot Access`**, set the **`Bot Access Rule`** to **`TRUE`** ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/7eacb3a7b7308312d33632feb4f3e5893ee3806fc0d515411f3c793355524c36/docs/assets/images/setup-labs/lab2_e5ad3b37-84bd-4140-a386-1fc94de188f9_Bot_Access.png) *** ## ✅ 2: Verification & Next Steps 1. **Wait for Processing:** 1. Now that we have configured the Moveworks User Identity Pipeline, **we will need to wait for the user ingestion cycle to complete** 1. In a typical environment, the user roster refreshes every 4 hours 2. If you are participating in a designated Moveworks Lab, your environment will refresh every 30 minutes. 2. **Confirm Completion:** 1. Check the `Imported Users` page, and confirm that: 1. You are able to find yourself in the user roster 2. The `Enabled Users` & `Bot Reachable Users` is greater than 0 3. You see when the ingestion cycle completed and when it is next scheduled to run ![](https://files.buildwithfern.com/moveworks.docs.buildwithfern.com/b2bd1f2a3e630d12d1ce86602579eaafba110d5c1143df5d1f2647e0a3040d28/docs/assets/images/setup-labs/lab2_a942fabd-cdd8-4005-8913-15ca1cd4d919_imported_users_view.png) **Next:** [Pre-Req: Installing the Moveworks Update Sets into ServiceNow](/ai-assistant/getting-started/labs/moveworks-setup/lab-prereq-installing-moveworks-update-sets-dd2f30af516547c9) — required before Lab #3 (Enterprise Search). This installs the Moveworks-provided update sets your ServiceNow instance needs to support knowledge ingestion. *** ## 🪞 3: Reflecting on This Configuration Through this guide, 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 create the Moveworks Service Account user * 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` |