Overview

To begin the Configuration process, navigate to User Identity > Import Users under the Core Platform module. If you are doing this configuration for the first time you will see a create button.

If an Identity Ingestion configuration already exists you will see a single configuration with it’s name, the last updated timestamp, and an edit button.

Configuring User Identity Ingestion

Step 1: Select sources to ingest from

This is where we define the external sources which will be connected to in order to ingest the user identity data from them. Please ensure the required connectors have been created to interact with the source systems.
If not, please follow this guide for Access Requirements in the source system and the steps to Setup Connectors.

We have a categorization under the sources here which is split between the Primary Source and the Secondary sources.

Primary source

The primary source refers to your main system used for user management. This is most commonly an Identity System like Microsoft Active Directory or Okta. When you configure a source to be the primary source in Moveworks, Moveworks will leverage the attributes from this source by default when importing users into the platform.

Let's consider an example. Assume we have the following 3 sources:

1. Okta - Primary
2. ServiceNow
3. Microsoft Graph

If Okta is configured as a primary source, and a user's department is set to Engineering in Okta, but Eng in ServiceNow, the final user object in Moveworks will contain the value Engineering for the department attribute in Moveworks.

Secondary sources

The other systems where you want to ingest the attributes of your employees are considered secondary sources.

Using the example above. Okta would be the primary source, and ServiceNow and Microsoft Graph would be the secondary source.

Secondary sources are required for overall AI Assistant functionality because in order for the employees to interact with various systems for operations like ticketing or being added to an Access Group, the employee identity in those sources need to be ingested on the Moveworks end for the interaction to take place.

Example: You might want some of the attributes of your users that reside in your ITSM for your ticketing plugin to work properly. Go ahead and add your ITSM connector under the secondary source in this case.

Step 2: Configure selected sources

After selecting various sources, let's add filters and configure each of the defined sources.

You will see a table with all the identity sources that you have previously selected. Here you will come across a "View Sample" button for each source. This is a quick way to check if the connector being used for the source system is configured correctly.

Clicking on "View Sample" makes a live API call to the source system and fetches the identity data using the default attributes.

Filters and Attributes List

On this page you can also apply filters for each source. There can be different types of filters based on the source.

For example, if you have selected ServiceNow as a source, you are given two options for filters.

1. Generic source filter: This is where you can give the ServiceNow API query to filter out users who should and should not be part of your final user set. Filtering can be on the basis of geography, email, department and many more. You can go to ServiceNow API documentation here, to learn more.
2. Attribute selection: Please define a list of attributes for the users identity which you would like to ingest from the source system. It is suggested to add all the attributes in this list here so the API call is filtered down to only ingest those attributes.

For example, if manager details is an attribute for an employee in your ServiceNow instance and you do not want this attribute to be part of final user profile, you can skip adding this attribute under filters.

You can add multiple filters for multiple sources as well.

For filtering out users based on an API query, take a look at the steps documented in the how to guide here.

📘

Moveworks recommends following the guidance below to filter our irrelevant users and keep the identity import running properly

Key to keeping our user ingestion process reliable is to reduce the data size as much as possible. This helps us avoid timeout errors. In general, there are two ways in which you can reduce the size of the data that we’re pulling from a customer system’s API - reduce the “width” or the “length”. Reducing the “width” of the data refers to pulling fewer attributes per user - i.e. explicitly defining which attributes we want to pull. Reducing the “length” refers to the total number of users we are pulling from the system, which can be done by applying a filter query to remove irrelevant accounts.

The best practice here is to filter our service accounts, conference room accounts, or other "non real people" accounts.

Step 3: Set join key

This is a very crucial step for creating the final user profile. After you have selected all your sources and added filters to each of them, Moveworks requires the selection of a single attribute that is common across all the other sources.
This attribute will be used as a key to merge the user data from all the integration sources that you have configured and unify them into a single unified user object.

The final user import will have all the unified user objects with a set of attributes sourced from the integration sources configured.

❗️

Please note that the join key is an immutable field and not editable after initial configuration. Be sure, to carefully configure which field is used here.

We strongly recommend against changing the primary key for user import. Changing the primary key will result in the full reconstruction of the user identity within Moveworks including the loss of all user preferences and all chat history. It will also require 1-2 days for the change to be completed so we highly recommend making the change on Friday evening to allow for the full weekend for the changes to take place. You will need to work with a Moveworks CSE to make this change.

Note: User email is most commonly selected as a join key since this attribute is common across all systems. Other common fields include employee_id, or User Principal Name (UPN).

Step 4: Add user profile overrides

This is the step where you define the overrides to the values of the final roster. When we ingest user data from multiple sources the final roster mainly comprises of the data coming from the Primary source.

Consider a scenario where Okta is the primary source and ServiceNow is the secondary source. You have applied filters and selected the attributes for both the sources. You have seen the sample user set and are satisfied with the attributes that are about to be ingested, but there is an attribute called "department" which is defined in the attribute section for Okta.

In the final user profile this attribute is crucial for you. But the value of this attribute is something that you do not want to pick from Okta but ServiceNow.

So basically you want the attribute "department" from Okta but you want it's value to be populated by an attribute called "user_department" from ServiceNow. This is the use case that you can execute by adding overrides.

For our example, the override will look something like this:

{

"department": {  
    "name": "snow.department"  
  }

}

Overrides are written in json format.

Step 5: Add bot service account

This is a very important step which is required in order for the Identity Ingestion Pipeline to succeed. After the Identity Ingestion configuration steps have been completed, please navigate to User Identity > Advanced Settings > Service Accounts under the Core Platform Module.

It is crucial to have a BOT service account defined using the below template which includes the service account information. This is required for the Moveworks AI Assistant to understand its own identity through different platform integrations.

For example, when reading comments from a Ticketing integration, Moveworks leverages the user_itsm_id_info[0].full_name to know which comments were made by itself versus made by another fulfiller to know if it should notify a user on the comments or not.

It is important for the Bot Service Account to have its own ITSM, IDAM, CHANNEL ID Info. for the identity pipeline to complete the ingestion successfully.

{
  "user_id_info": {
    "user_email": [
      "[email protected]"
    ],
    "channel_id_info": [
      {
        "integration_id": "movewebchat",
        "user_channel_id": "[email protected]"
      },
      {
        "integration_id": "msteams",
        "user_channel_id": "28:<Azure App Client_ID>"
      }
    ],
    "user_itsm_id_info": [
      {
        "integration_id": "jira_service_desk",
        "full_name": "M8 Service Account",
        "itsm_user_id": "svc-m8",
        "first_name": "M8 Service Account",
        "external_id": "<svc_account sys_id>"
      }
    ]
  },
  "user_tags": [
    "BOT"
  ],
  "email_addr": "[email protected]",
  "user_name": "M8",
  "role": "Virtual Assistant (Bot)",
  "department": "IT",
  "manager": "Zeeshan Yousuf",
  "record_id": "[email protected]",
  "full_name": "M8",
  "location": "slack"
}

The information which is added into the template is based on the Access Requirements for the source systems where the service accounts were created.

The email for the Bot service account can be set to anything fictitious, please ensure the domain of the email is inline with the current org email structure.

Step 6: Map Critical User Attributes

The following fields are critical to your AI Assistant's functionality. Ensure these are mapped for the corresponding functionality to work as expected.

First Name, Last Name, & Full Name:

These fields are used throughout the Assistant for various purposes, such as the Assistant greeting you or for the

Lookups plugin.

Timezone

Having the user's timezone populated in the roster is crucial for any ticket notifications sent by the bot. Various Moveworks plugins take the timezone field into account to ensure users only receive notifications during business hours. By default, if you do not configure timezone, it will leverage US PST. It is possible to configure a default timezone as well.

There are a few common ways timezone is configured (in order of preference below).

(1) Setting Timezone from Slack

Slack has timezone as part of the base mapper, so just add it in the **Override User Profile fields **(under Advanced Mode) like below:

If your customer uses Slack, we strongly recommend pulling timezone from Slack, since the Slack thick client pulls the user's timezone from their device. So if a user travels from CA to NYC, their timezone would update from PST to EST, the next time their device is connected to Slack, and then would update in Moveworks the next time identity ingestion runs for the org.

(2) Setting Timezone from a Field

If Slack is not an option, you can use a field from any other system. Be sure to validate that the values coming from these field are valid timezones (and not custom values), and that the values are populated for the majority of users.

To configure timezone from a field, you will need to map it from the source system, and then refer to it in the Override User Profile fields section using its integration_id.

(3) Deriving Timezone from Other Location fields.

In the case that you do not map timezone, you can derive timezone from other fields.

To enable the timezone resolver based on other location fields:

If you are leveraging the timezone resolver, Moveworks resolves timezone if this order:

1. city and country_code
2. state
3. timezone field
4. country_code
5. region

❗But be careful here. In the case that you have (city and country code) OR (state) the field will be calculated. However, if you have only a country or region the field will always be US/Eastern if the field is empty in the ServiceNow (or the source system).

(4) Configure Default Timezone

⚠️ If no timezone is defined, Moveworks will default to PST. If you know an organization has their HQ, with the majority of their employees in a different timezone, it is recommended to set that timezone as a default value in the roster merge template.

For example, if the customer is HQ in New York, you may add the following configuration to the Override User Profile Fields.

  "timezone": {
    "COALESCE()": {
      "items": [
        "snow.timezone",
        "\"America/New_York\""
      ]
    }
  }

Password Metadata

Utilized in Password Expiry Access Account plugin. Follow the steps in this guide to configure: How To Ingest Password Metadata

Country Code & Geocode Information

Utilized for Profile Boosting -- Follow the steps in this guide to configure: How To Ingest User GeoCode Information

Department and Location

These are used in the Lookups plugin and in Bot Performance Insights.

Manager

When we set up an org’s user roster, we require the user’s manager for facilitating approvals where the approval configuration requires a manager approval or displaying as the “supervisor” in the people lookup plugin.

For the purposes of our identity platform, we require manager_email to be mapped to each user roster entry. Generally, this is not something that is not always available in a user object - it requires some post-processing to lookup the manager after all users have been ingested. Follow the instructions in the how to guide to map manager.

✅ You have finished your configuration! Wait 24 hours and complete Step 7.

Step 7: Validate the Configuration was successful

Once you have waited 24 hours, navigate to User Identity > Imported Users

From here, you can navigate to the All Users section.

On the bottom left, you should see an option to Download the Current View.

From here, you can look through the export of the roster at each field and ensure they were mapped properly and that there are not too many empty or null fields mapped. Be sure to check the fields mentioned in Step 6 above.

Common Mistakes when Configuring Identity

• Admin-type users often have two accounts in some systems - e.g. 2 accounts in ServiceNow. We only choose one of those to link to their chat ID in the roster profile. They complain that they can’t check the status of some of their tickets because those tickets were created under the account that is not the one that’s linked to their identity user record. The customer might have a prefix for these users e.g: accounts that start with A-.
  • Fix: Filter these accounts out.
• Users can have different emails/join key in different systems. Users will have incomplete identity, and multiple features and capabilities of the AI Assistant will not work.
  • Fix: Ensure the user has the same join key in all integration systems. Be sure to follow the validation steps to ensure completeness of the user's identity profile.
• Timeouts: Fetching Users causes the identity Import to timeout from the integration APIs.
  • Fix: Filter to limit the # of users or # fields for the system (see the "Filters and Attributes List" section above).
• Alerts occur with multiple accounts with the same email.
  • Fix: You could add a filter to not retrieve certain accounts. Be sure to flag this to the customer, so they can fix this on their side.

FAQ

Q: Are there any built-in filters applied to user ingestion?

A: Yes, for example for Entra (fka Azure AD) user ingestion specifically, Moveworks will only ingest users that have accountEnabled eq true. This field on the user object must to be set to true, otherwise the Moveworks ingestion will skip over that user(s). In ServiceNow, Moveworks checks for active=true on the user object.