Old identity journey and migration steps

If your organization currently uses the old user identity journey, refer to Configure User Identity - Old Journey doc for more details.

If you want to migrate to the new revamped identity journey, follow the steps below.

Migration checklist

1. Verify joining keys — ensure your joining keys are mapped to the Moveworks Universal ID construct, which is standardized in the new journey.
2. New orgs are ready — all new organizations have the new journey enabled by default. If you encounter any issues, please contact your Moveworks Admin.

What’s available in the new identity journey

• Connector validation — test primary and secondary connectors before configuration.
• Pre-built source mappers — default mappers per system for seamless setup.
• JSON field editor — configure internal fields, such as user ID info, directly.
• DSL attribute mapping — validate and auto-complete mappings for supported systems.
• DSL testing for attributes — validate the values your attributes return from specific systems.
• Joining key testing — validate joining keys with DSL before saving.
• User preview — test with a sample user to verify the entire profile and confirm success before ingesting users.

Overview

Why identity configuration is critical for enabling Moveworks capabilities

The Moveworks AI Assistant always acts on a user’s behalf. To do that, it needs to know who they are in every system. Identity configuration is where the Assistant derives that knowledge from, and every downstream capability — ticketing, forms, knowledge — depends on it.

For example, take a simple user request: “My laptop won’t turn on after the macOS update, please raise an IT ticket.”

1. The Assistant works out the intent: file a ticket.
2. It looks up the person’s ITSM identity (ID) — their user record ID in ServiceNow or Jira. That is the account the ticket is raised under.
3. It reads their department and location, so the ticket reaches the right team at the right site.
4. It creates the ticket.

Without step 2 there is no requester to attach, and the ticket cannot be created at all. Without step 3, the routing destination is never set for the ticket.

Other patterns follow the same shape:

• “I need access to Salesforce.” The Assistant needs the user’s ID in your IDM, such as Okta, to initiate the request, and their manager’s ID to approve it.
• “What discount can I approve on this sales deal with Adobe?” The Assistant checks whether the user is part of the sales org using their ID, and only then surfaces the corresponding knowledge article on product discounts.
• “Who reports to me?” The manager relationship has to be resolved.

A complete user profile is what makes all of this possible. It tells the Assistant where the person exists in each system, what they are allowed to see, and how to reach them. Identity configuration is how Moveworks builds one such profile per person, filling the Moveworks user data dictionary for every ingested user.

High-level architecture of Moveworks user identity

How to start setting up identity configuration for your org

Before you begin

1. Know your sources. Decide which system is your primary source of truth for users and their attributes, and which secondary sources you need for additional users or attributes.
2. Create and authorize your connectors. Every source needs a working connector before you start.
3. Decide your joining key. It can only be set once per configuration save. Changing it later requires resetting your configuration and re-ingesting all users.

The joining key is extremely important when you have multiple sources configured. It is the common identifier used to match and merge user profiles across different sources, via a left join on the primary source.

For example, John Doe exists in both MS Graph (primary source, joining key: SAM account name) and ServiceNow (secondary source, joining key: external_id). John’s SAM account name is jdoe.

• The left join matches on jdoe from MS Graph.
• If ServiceNow’s external_id is not jdoe, all attributes for John from ServiceNow are dropped.
• If John’s SAM account name is empty or null in MS Graph, the user is excluded from ingestion entirely.

Steps to configure user identity

Step 1: Select sources

1. Set a primary source connector.
2. Set the secondary source connectors.
3. Test and validate each source. Ensure issues are fixed at this step so they do not affect downstream user ingestion.

You will encounter one of the following scenarios for each source.

Test is successful — the connector is valid and you can proceed.

Test fails on a built-in connector — there is an underlying issue with the connector, such as a 403 access forbidden error. Test the connector with a users API call in the API Playground. If no APIs are found for a system, define the path in the API manually and test to see what it returns.

Test fails on an Identity Gateway (HTTP) connector — testing is not supported for Identity Gateway sources, but your user ingestion remains unaffected. Go to Agent Studio > HTTP Actions and test a sample HTTP action. Fix the connector until you get a 200 Success code in the action response. See Custom User Ingestion with Identity Gateway for the full setup guide.

Step 2: Configure source mapping

How to view and add attributes per source

This is where you map user attributes from each connector to the Moveworks user object. For each connected system, decide which of its attributes fill which Moveworks user fields.

Moveworks ships default mappings for every supported system, so most orgs start with a working configuration.

Use View attributes to see what is already mapped before you add anything.

To map additional attributes:

1. Expand a source and click + ADD.
2. Pick the Moveworks user field you want your attribute mapped to.
3. Build the rule in the DSL builder. Use autocomplete to select the external attribute you want — it suggests the attributes that system actually returns.
4. Test the rule live for a user and check the output.
5. If it is your desired output, click SAVE.

How to test an attribute against a sample user

Click Edit against any attribute, then enter a user email to test the mapping against an existing user.

Which internal fields you can map

Beyond the standard profile, you can also map a set of internal fields based on your requirements.

The JSON editor, and when you need it

Most fields take a DSL expression in the mapping. The user_id_info fields — channel_id_info, idm_id_info, and itsm_id_info — are the exception: they hold an array of entries rather than a single value, so they can only be defined through the JSON editor.

Moveworks ships defaults for each system. You can edit those defaults, and map new attributes per source based on what your configuration needs.

Example: routing ServiceNow users to the Moveworks Web Assistant

Say ServiceNow is a secondary source for ingesting users. Its channel_id_info is empty by default — reasonably, since ServiceNow is not a chat platform. If you want every user ingested from ServiceNow to be reachable through the Moveworks Web Assistant, you need to define this mapping explicitly. Add a channel_id_info entry for ServiceNow and define its JSON mapping for Moveworks Web Chat.

This is the general shape of the problem for cross-mapping use cases. When the surface you want to reach a user on is not the system you got them from, user_id_info is where you close the gap.

Internal user email field mapping

If you are defining a new mapping for the user_id_info.user_email field across any source, always enclose the DSL expression in []. The field expects values in this list format only.

How to add filters and processors

Open a source and click the filter icon. You get two tabs: Filters and Processors.

Filters decide which users get ingested

Filters narrow which users Moveworks pulls from a source, and declare which attributes the source returns for them. Without a filter you ingest every account the connector can see — people who have left the company, service accounts, external guests — and each one counts toward your user count.

Filters are source-specific. Pick the one built for your system, or use the Generic Source Filter if there is no dedicated one. Always set your filters upfront to ensure you ingest the right set of users to start with.

Example: MS Graph Source Filter

• Azure AD Group ID — only ingest members of that group. Useful when you want to start with one department.
• OData Filter Query — the default is accountEnabled eq true, which skips accounts that have been switched off. Extend it to accountEnabled eq true and userType eq 'Member' to also exclude external guest accounts, so only your active employees are ingested.
• Attributes — Graph only returns the properties you ask for. Anything missing from this list arrives empty, however correct your mapping is.

Available filters

Processors fill in what cannot be derived from the source directly

Some fields cannot be mapped, because the source does not hold the exact user attribute value. Processors compute these values during ingestion.

Two common scenarios:

Resolving a manager. ServiceNow does not store your manager’s email address — it stores the manager’s sys ID. If you map that straight into manager_email, you end up with an ID instead of an email. So you map two things: each user’s own sys ID into internal_fields.manager_resolver, and their manager’s sys ID into manager_email. The Unified Resolve Manager Processor then looks up that sys ID against everyone being ingested, finds the person it belongs to, and replaces the ID with their email address. Approvals now reach a real inbox.

Deriving geocodes. No system gives you coordinates. You map country_code in source mapping, which holds a two-letter country code — DE for Germany, US for the United States. The User Geocode Processor reads that code during ingestion and works out the matching coordinates. This is what lets the Assistant apply German policy and route to the German support queue for a user in Germany, instead of treating the country as plain text it cannot act on.

How to view sample users

Click Sample Users to preview a set of users that will be ingested from this source.

Step 3: Configure override mapping

By default, every standard attribute on the final user profile comes only from your primary source. Override mapping is where you change that, one field at a time — either to take a field from a secondary system, or to fall back from one system to another when a value is empty.

Mapping an attribute on a secondary source in Step 2 is not enough. Until you add an override for that field here, the profile always keeps the primary source’s value. This is the most common reason a secondary attribute shows up empty.

For example, Workday is your primary source, but its office locations are out of date and ServiceNow has the current ones. Add an override for location pointing at ServiceNow — location now comes from ServiceNow, and every other field still comes from Workday.

You can override standard profile fields, internal fields, and custom attributes.

Geocodes: a special case

geocodes appears only in the override mapper, never in source mapping. This field is always derived from the country_code field present in the source mapper.

Geocodes turn “this user is in Germany” into coordinates the AI Assistant can reason about — so it can apply the right regional policy, route to the right regional support queue, surface the right office or holiday calendar, and answer location-dependent questions correctly. Without them, a user’s location is a plain string the Assistant cannot act on.

Step 4: Configure join key

Your joining key is the attribute that identifies the same person across all your systems. It is what turns several incomplete records into one complete profile.

For example, Workday is your primary source, with ServiceNow and Okta as secondary sources. Workday knows Jane’s department and manager, ServiceNow has her current office, and Okta has her login.

When the keys line up, the records merge. If all three sources return employee ID 40417 for Jane, Moveworks builds one profile with her manager, her office, and her login — enough for the Assistant to route her approval and answer questions about her office.

When a secondary source’s key does not match, data from that source drops out. If ServiceNow returns a different value, Jane still gets a profile from Workday, but her office is empty and anything that depends on her location stops working for her. Nothing looks broken. If the primary source’s key does not resolve, Jane gets no profile at all.

Pick an attribute whose value is the same in every system and does not change over time, or write a DSL rule to build the key from more than one attribute.

How to edit and test a joining key from a new source

Within the source, click Edit. Map the corresponding attribute and test with a user email. This validates that your source is not returning an incorrect or empty joining key.

Step 5: Validate final user profile and submit

This is where you dry run your identity configuration for sample users, before you save your changes.

Enter a user’s email address and click Show User Profile. This section tells you whether, for the given user email, the system was able to build a final user profile across multiple systems.

Configuration mistakes are invisible until users are already ingested, and by then fixing them means re-ingesting. This is the only place you see the finished profile pre-ingestion.

System attributes

System attributes appear per integration_id, based on the configuration set for all user_id_info fields across primary and secondary sources on the Configure source mapping screen. Click each toggle to view attribute-specific values.

How the test actually works

1. Moveworks makes a fetch user by email API call against every connected source — Okta, MS Graph, and so on — in parallel, using the email address you typed.
2. Each returned record is run through that source’s source mapping from Step 2, producing one mapped record per source.
3. Those mapped records are joined on the joining key from Step 4, such as SAM account name, and merged into a single profile anchored on the primary source, exactly as real ingestion would.
4. The merged result is what you see on screen.

The important consequence: the email only helps you locate the user. The joining key is what does the actual merging. When those two are different attributes, the test can fail even though real ingestion works fine — a single-user lookup returns fewer attributes than the full crawl does, so a source can come back with no joining key value at all.

Each source reports a merge status.

Where a field comes back empty, the screen tells you why under Sample Results.

Below is a sample scenario where the user test fails across multiple configured sources.

An error does not always mean something is wrong. The most common cause is simply that the person does not exist in that source. Before changing any configuration, re-run the test with a full-time employee who exists in every connected system.

If your joining key is not an email address, the Test with user screen may error out even though user ingestion succeeds. The test uses email to locate the user in the source, but the source may not return the attribute your joining key requires.

FAQs

General

Standard fields and internal fields

The User ID Info fields

Joining keys

Override mapping

Geocodes and derived fields

Testing and validation

Identity Gateway