> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.moveworks.com/_mcp/server.

# Connect ServiceNow

Prepare your ServiceNow instance and connect it to Moveworks so the AI Assistant can search knowledge, look up records, and act on tickets in your instance.

**For administrators.** This page covers the ServiceNow-side preparation, the Moveworks-side connection, and the user ingestion that joins the two. Once complete, continue to [Configure Enterprise Search](/ai-assistant/getting-started/implement-on-servicenow/configure-enterprise-search), [Configure Forms](/ai-assistant/getting-started/implement-on-servicenow/configure-forms), and [Configure Ticketing](/ai-assistant/getting-started/implement-on-servicenow/configure-ticketing).

## Before You Begin

* You need admin rights in the ServiceNow instance you are connecting (or a ServiceNow admin who can complete steps 1 and 2 for you).
* You need access to **Moveworks Setup** in your Moveworks tenant. If this is your first time accessing Moveworks, see [First-Time Login via Magic Link](/service-management/moveworks-setup/first-time-login-via-magic-link) and [Roles and Permissions](/service-management/administration/manage-roles-and-permissions-for-moveworks-applications).
* If you are connecting a production instance, follow your organization's change-control process. We recommend completing these steps in a sub-production instance first.
* Open ServiceNow and Moveworks Setup in separate browser tabs, and keep a notes document handy: this task captures several values you will re-enter later.

## Procedure

### 1. Install the Moveworks Update Sets

Install the [Moveworks Update Sets](/service-management/access-requirements/update-set-modules/servicenow-update-sets) in the documented order. At minimum you need `moveworks.base` (always first) and `moveworks.acl` (required for Moveworks to evaluate user criteria on knowledge and catalog items). Installing `moveworks.base` adds the `moveworks_user` role to your instance; you will grant it to the integration account in the next step.

On an instance with existing customizations:

* **Preview** each update set before you **Commit**, and resolve any preview problems with your ServiceNow admin. Collisions are normal on customized instances; do not blind-accept.
* Install in sub-production first and validate there before promoting to production.
* If you need to remove an update set later, use ServiceNow's **Back Out** on the committed update set.

### 2. Choose and Prepare the Integration Account

Moveworks authenticates to ServiceNow as a single account. Anywhere Moveworks documentation or examples show `admin`, read it as **the account you choose here**: your values (user ID, email, `sys_id`, credentials) will differ accordingly.

You have two options:

* **The built-in `admin` user (simplest).** Appropriate for a Personal Developer Instance or a disposable sandbox, where the out-of-the-box `admin` account already has everything Moveworks needs.
* **A new admin account you create (recommended for any shared or production instance).** Create a ServiceNow user for Moveworks with the roles listed in the [ServiceNow Access Requirements](/service-management/access-requirements/ticketing-systems-and-itsms/servicenow-access-requirements): ITIL, Approval Admin, Flow Operator, Catalog Admin, UI Policy Admin, and Personalize Dictionary.

Then, on the chosen account's user record in **User Administration > Users**:

![User Administration menu showing the Users option in ServiceNow](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/51d9cec66b6f6c60d8744d806e771562d637b8344ab3f1a91f4f0adcabf69c84/docs/assets/images/setup-labs/lab0pdi_user_administration_menu.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=b45db6f5bf309c70001cfc49b8eb7e0f06126e886ad8b2d045764b1924ec7209&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

1. **Grant the `moveworks_user` role** (added by the `moveworks.base` update set in step 1) **and the `snc_basic_auth_api_access` role**. ServiceNow requires `snc_basic_auth_api_access` for an account to authenticate inbound REST API calls with basic authentication; without it, the connector's API calls fail even with valid credentials.

2. **Confirm the Email field is populated**, and set it if empty. The built-in `admin` account on a fresh instance often has no email. Moveworks requires this value in step 5: it is how the Bot Account joins to the ingested user roster.

3. **Set the Time zone field to `GMT`.** This keeps audit timestamps and scheduled behavior consistent between Moveworks and ServiceNow.

   ![User record with the Time zone field set to GMT](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/db68c1bb32a5295d44ec9ee39c5be692fcbbf6359e71bc5de499a5138de95459/docs/assets/images/setup-labs/lab0pdi_admin_timezone_gmt.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=4fc9e988a3f4bca30fb23961d790480da845c03e88b80b86460816cc1f9dd52c&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

4. **Capture the account's 32-character `sys_id`.** With the user record open, use any of these:
   * Click the hamburger menu (three lines, top-left of the form), then **Copy sys\_id**.

     ![Hamburger menu on the user record showing the Copy sys\_id option](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/7435c171f3d7c029f71377cac4229b1888bf2efa7c8a687a3cceb1b50ebe2613/docs/assets/images/setup-labs/lab0pdi_copy_sysid_hamburger.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=9ce21764c71554d3e3360528222f97c38925996498d69e713a1b9495e56d1c11&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

   * Right-click the gray form header, then **Copy sys\_id**.

     ![Right-click context menu on the record form header showing the Copy sys\_id option](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/98a962d633264eb2724324fda468317bb105ffaa36e69e1a4351c2de4184d6bb/docs/assets/images/setup-labs/lab0pdi_copy_sysid_rightclick.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=3ea301d9343e757e5b05588c55a1cc88b177c2ed85b3510ac952058e517d781d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

   * Copy it from the URL, which contains `sys_user.do%3Fsys_id%3D{sys_id}`.

**If you copy the `sys_id` from the URL, do not include the `3D` prefix.** `%3D` is a URL-encoded equals sign, not part of the identifier. The `sys_id` is the 32-character hex string that starts immediately after `%3D`: `ed65ebcf8372e690cbcdc396feaad380`, not `3Ded65ebcf8372e690cbcdc396feaad380`.

5. **Record your instance URL and the account's user ID, password, email, and `sys_id`** in your notes. Steps 3 and 5 consume all five values.

### 3. Create the Connector

In **Moveworks Setup**, go to **Connectors > Built-in Connectors**, select **ServiceNow**, and create the connector using your instance URL and the integration account's credentials, then test it. See [Connectors](/agent-studio/connectors) for the step-by-step guide.

![Built-in Connectors page in Moveworks Setup with ServiceNow selected as the system to connect to](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/6feb8a3e959b15ad20d4db2ec370b87c9d458553495f548dd788caac97e0e137/docs/assets/images/setup-labs/lab1_be1c2c2d-d004-4555-a8dc-bb2723825f11_now_connector.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=46a090e3eca41045869e7bf081ed85be4dbd43fdba4c5cbaa4f0382ccf89d705&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Choose the connector name carefully; it cannot be changed once set.** Every later configuration that references this connector - user ingestion, Enterprise Search, Forms, Ticketing, and the Bot Account's Integration ID - must use exactly the name you enter here. Record it in your notes, and wherever documentation shows an example connector name, substitute yours.

![Connector Name field on the Credential Details form, noting the name cannot be changed once set](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/ec7ed050dd65a46685b5a5da1427e553b2033dceceab30d1009df9c77c4f709c/docs/assets/images/setup-labs/connector_name_field.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=912f9a7d67aa73dc601135ff3afc1a3860c4932fc60d4cba0b331446773cba65&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

### 4. Ingest Users

The user roster is the backbone of Moveworks identity: it determines who can use the AI Assistant and joins each chat user to their ServiceNow records. Ingestion pulls user data from ServiceNow through your connector, and a **joining key** (email by default) matches each person across systems - which is why the joining key must be unique, permanent, and present in every connected system. See [Ingest Users](/agent-studio/core-platform/user-identity/ingest-users) for full detail.

In **Moveworks Setup**, go to **User Identity > Identity Configuration**. The wizard has five steps:

1. **Select sources.** Choose your ServiceNow connector as the primary source and click **Test** to confirm it is reachable. Leave secondary sources empty unless you also ingest from an HRIS or IdP.

   ![Identity Configuration wizard with the ServiceNow connector selected as the primary source](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/fe307c7883f9ab438764b18b0a680c84f2faa13ab06d2b35f66f3fb28658fb87/docs/assets/images/setup-labs/lab2_new_identity_1.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=83e822703ec834f3a55a0d49ed7b4d152630a23fcdb377b3ed4a5dff3d2d3786&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

2. **Configure source mapping.** Click the person icon on your source row to view sample users and confirm real records return (if none do, recheck your connector credentials). Then open the filter (funnel icon) and add the API query string `active=true` so only active users are ingested. Under **Processors**, add and enable the **User Timezone Processor** and the **Unified Resolve Manager Processor** (resolves each user's manager reference into a usable profile attribute). The per-attribute field mappings ship with sensible defaults; you can inspect or override any of them later.

   ![Filter dialog on the ServiceNow source with the API query string set to active=true](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/e1f362497c429f748d70d4b1a7ac61bb1d298e60fe47807f265736d12f79d70e/docs/assets/images/setup-labs/lab2_new_identity_8.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=5c493fdf102922d02051f29b7d9bd76491439cf0c66a2435e231a412045dd4ab&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

3. **Override field mapping.** Only used with multiple sources; with ServiceNow as your single source, leave empty.

4. **Set joining keys.** Confirm the joining key resolves to the user's email address (the default).

5. **Test with user.** Enter your own email and click **Show User Profile**. You should see real values for attributes like name, email, role, and department; `Null` results are expected for attributes you have not customized. When it looks right, click **Save Configuration**.

   ![Test with user step showing resolved profile attributes for a sample user](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/33ee4f01c6852c8cb83baf9142ffb1bab34df4fcd8a736ffe902d4ccee78a380/docs/assets/images/setup-labs/lab2_new_identity_19.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=68436cd421dda01bee7dd132beeadb419913e2ee55dcd2d58ffe56fc6fb36e27&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

After saving, the ingestion cycle runs on a schedule (typically every 4 hours). When it completes, verify on the **Imported Users** page: you can find yourself in the roster, and **Enabled Users** and **Bot Reachable Users** are both greater than zero.

![Imported Users page showing the ingested roster with enabled and bot-reachable counts](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/b2bd1f2a3e630d12d1ce86602579eaafba110d5c1143df5d1f2647e0a3040d28/docs/assets/images/setup-labs/lab2_a942fabd-cdd8-4005-8913-15ca1cd4d919_imported_users_view.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=fba88c511f84925df722fc7a3ebe6984f80009cf14fcac92e7d379ca15a40e23&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Never create a duplicate user record.** Ingestion drops records with duplicate emails. If a person already exists in ServiceNow (synced from your identity provider), confirm their record is **Active** with a correct email instead of creating a second one.

### 5. Configure the Bot Account

On the **Bot Account** page in Moveworks Setup (**User Identity > Advanced Settings > Bot Account**), enter the values you captured in step 2. These fields must exactly match the integration account in ServiceNow; mismatched values cause Moveworks to fail to authenticate actions on behalf of users.

| Bot Account Field    | Value                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Email Address**    | The email set on the integration account's ServiceNow user record (step 2)                                                 |
| **Unique Record ID** | Same as the email address. This must match the joining key configured during user ingestion; duplicate values are dropped. |
| **External ID**      | The integration account's 32-character `sys_id` (step 2)                                                                   |
| **ITSM User ID**     | The integration account's ServiceNow user ID (`admin` if you chose the built-in account)                                   |
| **Integration ID**   | The connector name from step 3                                                                                             |

![Bot Account page in Moveworks Setup with the Email Address, Unique Record ID, ITSM User ID, External ID, and Integration ID fields highlighted. The example values shown (admin@example.com, snow) are placeholders; enter the values for your chosen account.](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/339b61bb02229961b31bc280fed8cd2c5e7b57bbc10e1a228e8f44f8877dbe88/docs/assets/images/setup-labs/lab2_46df36dd-9609-4b52-b769-bcb6aa579f4f_new_service_account_ui.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=950c78ee3f96ae913f03e26293755b7ffce4efb49e29eaf2d3aa80660e865273&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

See the [Service Account Configuration Guide](/agent-studio/core-platform/user-identity/service-account-configuration-guide) for a multi-system reference example.

### 6. Set the Bot Access Rule

The Bot Access Rule is the gate that decides which ingested users are allowed to interact with the AI Assistant. Until it is configured, being in the roster is not enough.

1. In **Moveworks Setup**, go to **User Identity > Bot Access**.
2. Set the **Bot Access Rule**. Setting it to `TRUE` grants access to every ingested user; to roll out gradually, use a DSL rule instead (for example, scoping by department or a pilot group) and widen it later.
3. **Save**.

![Bot Access page in Moveworks Setup with the Bot Access Rule set](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/moveworks.docs.buildwithfern.com/7eacb3a7b7308312d33632feb4f3e5893ee3806fc0d515411f3c793355524c36/docs/assets/images/setup-labs/lab2_e5ad3b37-84bd-4140-a386-1fc94de188f9_Bot_Access.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260826%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260826T065714Z&X-Amz-Expires=604800&X-Amz-Signature=27cce8109b572af967cce326681f5a19012dbeb1a7b7366b6b287ac598fc388f&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

**Passing the Bot Access Rule alone doesn't make the AI Assistant reachable.** Users also need at least one surface to talk to it: an integrated chat platform (Slack, Teams, and so on), My Moveworks on the web, or an Embedded AI Assistant on a portal behind your SSO.

## Result

Moveworks is authenticated to your ServiceNow instance: the update sets are committed, the connector test passes, users are ingesting into the roster on a schedule, the Bot Account fields match the integration account's real values in ServiceNow, and the Bot Access Rule defines who can use the AI Assistant.

## What to Do Next

* [Configure Enterprise Search](/ai-assistant/getting-started/implement-on-servicenow/configure-enterprise-search) so the AI Assistant can answer from your knowledge articles.
* [Configure Forms](/ai-assistant/getting-started/implement-on-servicenow/configure-forms) so users can find and fill catalog items in chat.
* [Configure Ticketing](/ai-assistant/getting-started/implement-on-servicenow/configure-ticketing) so users can file, track, and resolve tickets - and so form submissions complete.
* Work through the [Moveworks Implementation Starter Guide](/ai-assistant/getting-started/moveworks-best-practices/how-to-enable-your-moveworks-assistant/moveworks-implementation-starter-guide) for the full rollout, and complete the [Launch Checklist](/ai-assistant/getting-started/moveworks-best-practices/how-to-enable-your-moveworks-assistant/go-live-checklist) before announcing the AI Assistant.