What is user identity?

Overview

Every employee in a organization has a unique system ID or profile in the systems with which Moveworks integrates (i.e. Chat, IDAM, ITSM, etc). For Moveworks to complete actions across systems on the behalf of a user, it needs to have knowledge of all of the system IDs for the given user. For example:

• When a user wants to check the status of their tickets, Moveworks only “sees” the user’s chat ID in the inbound message. To find and return the user’s tickets in the ITSM system, Moveworks needs to know that user’s ITSM System ID, as well as their Chat System ID.
• When Moveworks polls the Identity system for locked accounts, it only “sees” the System IDs for the accounts that are locked in the Identity System. To send lockout notification messages to those users in the chat system, it needs to be able to correlate those Identity IDs to the corresponding Chat IDs.

To support these scenarios, Moveworks builds a User Identity store with a single unified User Profile for every employee in an organization. The Moveworks User object contains user profile information as well as External System IDs sourced from the systems that your organization choses to integrate with Moveworks. We commonly refer to these systems as "sources", and the Moveworks User Profile as the "Moveworks User Object".

📘

Note: It is not mandatory to configure User Identity Import for every system you integrate with Moveworks.

For example, if you are leveraging a connector in Agent Studio, you do not need to configure User Identity for that Connector. However, many built-in plugins may require User Identity to be configured (e.g: Access Groups, Access Account, Ticketing, etc.)

User Import Process

To build the Moveworks User Profiles, Moveworks imports users from sources it is integrated with. This process consists of the following steps:

1. Fetch: Pull the list of all user profiles from each source into a JSON file. This usually involves an operation to List all users per each source e.g: "GET /users"
2. Map: Once Moveworks has the raw profiles of the users, it takes the raw JSON user profiles and maps them to standardized Moveworks User objects, which is required for further processing.
3. Process: Once it has the preliminary user profiles for each source, it applies post-processing steps to the users. For example, UserGeocodeProcessor extract a user's geocode based on their country and gets used for Profile Boosting), and serPasswordMetaInfoProcessor calculates the password expiry date using the password last set field. Similar to the UserGeocodeProcessor, and UserPasswordMetaInfoProcessor, there are a variety of other processors to filter, process, augment and enhance information on the Moveworks on the user profile.
4. Merge/Join: Lastly, Moveworks joins the processed profiles from each source together into the final Moveworks user profile. This joining process does the following:
   • It joins the system specific profiles based on a single merging attribute / joining key.
   • It assigns each Moveworks user profile a unique Moveworks User ID, which is a hash of the joining key.
   • It automatically extracts the external system id's from each source system and stores them under external_system_identities on the User Object.
   • It applies the mapping configuration that specifies from which source to gather each attribute from when constructing the final Moveworks User Object.
   • This step runs validations
5. Validator: This step runs duplicate user validation as well as large Data Change Protection. For example if your primary data source returns more than 25% less users. The large data change protection validator will kick in and ensure that the Identity store does not get updated with a faulty data change.
6. Load: This final step loads the user objects into the relevant backend User data stores.

This entire process runs every 4 hours, and follows the Ingestion Schedule defined here.

Duplicate User Handling

Moveworks identifies duplicates using the configured merging attribute (e.g., email). A “duplicate” means multiple records in the primary source share the same merging attribute value.

How duplicates behave within a single source

If multiple raw records in any integration (primary or secondary) share the same merging attribute, Moveworks automatically:

• Keeps only the last record for that key (in iteration order).
• Overwrites earlier records silently.

As a result, each integration contributes at most one record per merging attribute into the final Moveworks Identity Store.

Duplicate validation on the primary source

After merging records across sources, Moveworks performs duplicate validation only on the primary source. There are 2 main scenarios of this process to understand:

Scenario 1: If duplicates < 5% of primary-source users:

• Ingestion continues.
• All users involved in duplicate sets are skipped for that run (none of the duplicate accounts are imported or updated).
• If a user was successfully ingested in a previous run, that user remains in the system with older data, but is not updated during this run.

Scenario 2: If duplicates ≥ 5%:

• Moveworks fails the ingestion run for the primary source.
• No users from that run are imported or updated until duplicates are resolved at the source.

Primary vs secondary sources:

1. Only the primary source can create new Moveworks users.
2. Secondary sources cannot create new users; they only serve to enrich users that already exist in the primary source and are being imported from the primary source.

Because each source collapses duplicates internally (keeping only one record per key), the final merged users typically contains one record per merging attribute, and the 5% threshold rarely triggers except in misconfiguration scenarios.

📘

For details on adding filters to Filter out Duplicate Users, review the documentation here.

Configuration options

View the configuration guide here for details on configuring Moveworks User Identity when implementing Moveworks.

If you have already implemented Moveworks, the how-to guides for other common configuration tasks.

FAQs

Q: How are users deleted/removed?

A: When Moveworks polls your primary source system for users every four hours, it checks for new user profiles, updated user profiles, and deleted user profiles. If a deleted user profile is found, and if that profile continues to show as deleted in the user set over seven days, the user profile is permanently deleted.

Q: A user was able to talk to the Moveworks yesterday but today it always responds with a message that begins: "Sorry..." or "I am not enabled"

A: If all messages are responding with the same error message, there are a few reasons this could be happening:

1. The user does not exist in the Moveworks Roster. This means they do not exist in the primary source, and therefore their user record is not making it to the final merged roster.
2. The user exists in the Moveworks Roster, but their chat integration external identity is not mapped. This means Moveworks cannot identify who the user is.
3. The user exists in the Moveworks Roster, but is not enabled for bot access. Usually the bot indicates this scenario as such, rather than sending a generic error message.

Q: A user is able to talk to the Moveworks and everything works as expected, but whenever they try to look up tickets or try to get access to a software/group, the bot responds with an error message.

A: This usually means the user exists in the roster, but similar to the above, their ticketing system ID or IDAM system ID is not mapped. Therefore, action cannot be taken on behalf of the user, because it is unable to understand who the user is in these systems.

Q: What fields exist on the Moveworks User Object?

A: Please refer to the User Attribute Reference documentation to see the fields on the Moveworks User Object.

Q: How does a Service Account and a Contractor Account relate to User Identity?

A: Both a Service Account and a Contractor Account represent distinct identity types that are ingested into the User Roster, but they serve different purposes:

• Service Account: This is a non-human platform identity used for System Integration (e.g., automated actions, user ingestion) and operates with Non-Interactive API Access under the principle of Least Privilege. Its profile is necessary for the bot to perform its core functions.
• Contractor Account: This is a human, interactive identity used by the Moveworks Implementation for Impersonation, Testing, and Validation during implementation. It requires Interactive Login (via SSO/web portal) and is given Customized Permissions to mirror a standard employee's experience for rigorous UAT testing.

Both accounts must be requested and set up prior to implementation, as the Service Account is critical for the bot's core functionality, and the Contractor Account is critical for successful testing and launch readiness.