> This page is for Platform Management.

> 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.

# User Ingestion Filters Guide

## Overview

User ingestion filters control **which records** and **which fields** are pulled from your identity source before any processing occurs. Filtering at the source level reduces data transfer, speeds up ingestion, and ensures Moveworks only works with the users that matter for your deployment.

There are two independent dimensions to every filter:

* **Record filter** — Which users to import (e.g. active employees only, a specific department, a specific Azure AD group)
* **Attribute list** — Which fields to import for each user (e.g. email, name, department, manager)

Both are optional. If you configure neither, Moveworks imports all available users with all available fields. **Only add a filter if you have a specific reason to restrict the import.** Over-filtering is a common source of issues — if users are unexpectedly missing from Moveworks, an incorrect filter is usually the cause. When in doubt, start with no filter and add restrictions incrementally.

> **Warning**
>
> **Specifying any attributes overrides the entire default field list.** If you add even one attribute (e.g. `department`), only that field and a small set of system-required fields will be imported — all other fields are dropped. Always include every field you need in the attributes list, not just the new one you are adding.

![The Filters and Attribute List panel in Moveworks Setup](/_fern-img/b076ac0543da868f6accdf352ee760ab79833d4c0f6db296f78be13fc40fb9ab.webp)

---

## How to Configure

**Navigation in Moveworks Setup:**

`Import Users → Connectors → [select your connector] → Configure Selected Sources → Advanced Mode → Filters and Attribute List`

The **Advanced Mode** toggle exposes the filter configuration panel. Inside, you will find:

* **Filters** — One or more filter entries, each defining which records to pull from this source
* **Attribute List** — A comma-separated list of field names to import

You can add multiple filter entries to import users from several groups or apply different criteria — these are combined as a **union** (OR), not an intersection. For example, two MS Graph filters with different Group IDs will import users from both groups.

---

## Quick Reference

| Source                      | Filter Type                                        | Supports Record Filter               | Supports Attribute List   |
| --------------------------- | -------------------------------------------------- | ------------------------------------ | ------------------------- |
| Any                         | [Generic Source Filter](#generic-source-filter)    | Yes — source API syntax              | Yes                       |
| Azure AD / Microsoft Graph  | [MS Graph Filter](#microsoft-graph-azure-ad)       | Yes — OData + Group ID               | Yes                       |
| SharePoint OneDrive         | [SharePoint OneDrive Filter](#sharepoint-onedrive) | Yes — OData + Group ID               | Yes                       |
| Salesforce                  | [Salesforce Filter](#salesforce)                   | Yes — SOQL                           | Yes                       |
| Exchange Online             | [Exchange Filter](#exchange-online)                | Yes — PowerShell                     | Yes                       |
| Google Workspace            | [Google Workspace Filter](#google-workspace)       | No — all domain users returned       | Yes — custom schemas only |
| Okta                        | [Generic Source Filter](#okta)                     | Yes — Okta filter syntax             | No                        |
| ServiceNow                  | [Generic Source Filter](#servicenow)               | Yes — Encoded Query                  | Yes                       |
| Workday                     | [Generic Source Filter](#workday)                  | Yes — full WQL query (WQL mode only) | No                        |
| GitHub                      | [GitHub Filter](#github)                           | Org scope only                       | No                        |
| Confluence (Cloud)          | [Confluence Filter](#confluence)                   | Group scope only                     | No                        |
| Confluence (Server/On-Prem) | [Confluence Server Filter](#confluence-server)     | Group scope only                     | No                        |
| SharePoint Online           | [SharePoint Online Filter](#sharepoint-online)     | Site membership scope only           | No                        |
| Cherwell                    | [Cherwell Filter](#cherwell)                       | Business object scope                | Yes — field IDs           |
| FreshDesk                   | [FreshDesk Filter](#freshdesk)                     | Contacts always; agents optional     | No                        |

---

## Common Scenarios

Common starting points across sources. Click any source name to jump to its full configuration reference.

### Filter by email domain

| Source                                | Configuration                                                 |
| ------------------------------------- | ------------------------------------------------------------- |
| [Azure AD](#microsoft-graph-azure-ad) | OData Filter: `endswith(userPrincipalName, '@contoso.com')`   |
| [Exchange Online](#exchange-online)   | PowerShell Filter: `PrimarySmtpAddress -like '*@contoso.com'` |
| [ServiceNow](#servicenow)             | API Query String: `emailENDSWITH@contoso.com`                 |

Full Azure AD example with attributes:

```
Azure AD Group ID: (leave empty)
OData Filter: endswith(userPrincipalName, '@contoso.com')
Attributes: mail, displayName, givenName, surname, jobTitle, department, officeLocation
```

### Import active employees only

| Source                                | Configuration                                                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Azure AD](#microsoft-graph-azure-ad) | OData Filter: *(leave empty — `accountEnabled eq true` is applied automatically)*                                                                    |
| [Okta](#okta)                         | [Use an Ingestion Processor and filter by Field Value or Rule](/platform-management/user-identity/mw-setup-identity/user-ingestion-processors-guide) |
| [ServiceNow](#servicenow)             | API Query String: `user_name!LIKEADMIN^title!=Contractor`                                                                                            |
| [Salesforce](#salesforce)             | SOQL Condition: `WHERE IsActive = true AND UserType = 'Standard'`                                                                                    |
| [Exchange Online](#exchange-online)   | PowerShell Filter: `RecipientTypeDetails -eq 'UserMailbox'`                                                                                          |

### Filter by department

| Source                                | Configuration                                                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Azure AD](#microsoft-graph-azure-ad) | OData Filter: `department eq 'Engineering'`                                                                                                          |
| [Okta](#okta)                         | [Use an Ingestion Processor and filter by Field Value or Rule](/platform-management/user-identity/mw-setup-identity/user-ingestion-processors-guide) |
| [ServiceNow](#servicenow)             | API Query String: `department=Engineering`                                                                                                           |
| [Salesforce](#salesforce)             | SOQL Condition: `WHERE IsActive = true AND Department = 'Engineering'`                                                                               |
| [Exchange Online](#exchange-online)   | PowerShell Filter: `RecipientType -eq 'UserMailbox' -and Department -eq 'Engineering'`                                                               |

### Scope to a group or team

| Source                                  | Configuration                                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------------- |
| [Azure AD](#microsoft-graph-azure-ad)   | Azure AD Group ID: `<object-id-of-group>`                                             |
| [Confluence](#confluence)               | Group ID: `61fb4ba0-49fc-4300-9951-f45c00000001` *(group UUID, not display name)*     |
| [GitHub](#github)                       | Organization Name: `my-company`                                                       |
| [SharePoint Online](#sharepoint-online) | Sites: `ITPortal` *(imports users with site access — [see note](#sharepoint-online))* |

### Import multiple groups (Azure AD)

Create two separate filter entries under the same connector. Users in either group are imported (union).

**Entry 1:**

```
Azure AD Group ID: <group-1-id>
Attributes: mail, displayName, givenName, surname, jobTitle, department
```

**Entry 2:**

```
Azure AD Group ID: <group-2-id>
Attributes: mail, displayName, givenName, surname, jobTitle, department
```

### Add a new field without losing existing fields

If your current import has no attributes configured (all fields returned), and you want to start explicitly importing `department`:

**Before (no attributes set — all fields returned):**

```
Attributes: (empty)
```

**After (wrong — drops all other fields):**

```
Attributes: department
```

**After (correct — re-include everything you need):**

```
Attributes: mail, displayName, givenName, surname, jobTitle, department,
            officeLocation, mobilePhone, employeeId, manager.displayName
```

### Exclude service or system accounts

| Source                                | Configuration                                                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Azure AD](#microsoft-graph-azure-ad) | OData Filter: `userType eq 'Member'`                                                                                                                 |
| [Okta](#okta)                         | [Use an Ingestion Processor and filter by Field Value or Rule](/platform-management/user-identity/mw-setup-identity/user-ingestion-processors-guide) |
| [ServiceNow](#servicenow)             | API Query String: `user_name!LIKEADMIN^user_name!LIKESVC`                                                                                            |
| [Salesforce](#salesforce)             | SOQL Condition: `WHERE IsActive = true AND UserType = 'Standard'`                                                                                    |
| [Exchange Online](#exchange-online)   | PowerShell Filter: `RecipientTypeDetails -eq 'UserMailbox'`                                                                                          |

---

## Generic Source Filter

The Generic Source Filter is available for every integration source. It accepts a raw query string and passes it directly to the source system's API — Moveworks does not validate or transform it.

Some sources ([Azure AD](#microsoft-graph-azure-ad), [Salesforce](#salesforce), [Exchange Online](#exchange-online), [SharePoint OneDrive](#sharepoint-onedrive)) also have dedicated filter types that expose more options like Group ID scoping or attribute lists. For **Okta**, **ServiceNow**, and **Workday**, the Generic Source Filter is the only supported option — they do not have dedicated filter types. See the subsections below for the correct query syntax and worked examples for each.

| Field                | Description                                       | Example                                  |
| -------------------- | ------------------------------------------------- | ---------------------------------------- |
| **API Query String** | Filter query using the source's native API syntax | `profile.login ne "login@example.com"`   |
| **Attributes**       | Comma-separated field names to import             | `email, firstName, lastName, department` |

### Okta

Okta uses an OData-like filter syntax. The query string maps to the `filter` parameter on the [Okta List Users API](https://developer.okta.com/docs/reference/api/users/#list-users-with-a-filter).

**What Moveworks applies automatically:** All non-deprovisioned users are included by default — statuses `ACTIVE`, `STAGED`, `PROVISIONED`, `RECOVERY`, `PASSWORD_EXPIRED`, and `LOCKED_OUT` are pre-filtered in. Your query string is ANDed on top of this base filter.

**Narrowing by status:** Adding `status eq "ACTIVE"` restricts the import to only ACTIVE users — it excludes STAGED, PROVISIONED, RECOVERY, PASSWORD_EXPIRED, and LOCKED_OUT users. Only add it if you specifically need to exclude those statuses.

**Supported Fields:** The following fields are supported for filtering via the `filter` parameter:

* `status`
* `lastUpdated`
* `id`
* `profile.login`
* `profile.email`
* `profile.firstName`
* `profile.lastName`

**Operators:** `eq`, `ne`, `lt`, `gt`, `le`, `ge`, `and`, `or`, `not` (see [Okta filter operators](https://developer.okta.com/docs/reference/core-okta-api/#filter))

---

### ServiceNow

ServiceNow uses Encoded Query syntax. The query string maps to the `sysparm_query` parameter on the [ServiceNow Table API](https://developer.servicenow.com/dev.do#!/reference/api/sandiego/rest/c_TableAPI).

**What Moveworks applies automatically:** `active=true` is always prepended. Your query string is appended with `^` (AND). You do not need to add `active=true` yourself.

**Operators:** `=`, `!=`, `^` (AND), `^OR` (OR), `LIKE`, `NOT LIKE`, `IN`, `NOT IN`, `STARTSWITH`, `ENDSWITH` (see [ServiceNow Encoded Query docs](https://developer.servicenow.com/dev.do#!/guides/sandiego/now-platform/tpb-guide/encoded_query_strings))

**Example — Import only employees (not contractors):**

```
user_name!=admin^title!=Contractor
```

**Example — Import a specific department:**

```
department=IT
```

**Example — Import users from a specific location:**

```
location=New York
```

**Example — Combine conditions (`^` = AND):**

```
department=Engineering^title!=Intern^u_employee_type=Full-Time
```

**Example — Exclude system/service accounts:**

```
user_name!LIKEADMIN^user_name!LIKESVC
```

**Example — Specify which fields to import:**

```
API Query String: department=Engineering
Attributes: user_name, email, first_name, last_name, department, title, manager
```

**Attributes** map to the `sysparm_fields` parameter on the ServiceNow Table API — use exact ServiceNow field names (e.g. `user_name`, not `username`). Leave empty to return all fields.

---

### Workday

> **Warning**
>
> Workday filter support is only available in **WQL mode**, which must be enabled in your org's Workday configuration. In standard REST mode, the filter string is ignored entirely. Contact your Moveworks implementation team to confirm which mode your org uses.

In WQL mode, the filter string **replaces the entire default WQL query** — it does not append to it. You must write a complete, valid WQL SELECT statement.

The default query Moveworks runs (when no filter is configured):

```sql
SELECT workdayAccount{userName1}, worker{workdayID}
FROM indexedAllWorkers
(dataSourceFilter = indexedAllWorkersFilter,
 includeSubordinateOrganizations = false,
 isActive = false)
```

> **Info**
>
> `isActive = false` in the default query does **not** mean "import inactive users." In Workday's WQL syntax, this parameter controls whether the index filter applies an additional active-status restriction — `false` means "do not apply a secondary active-status constraint on top of `indexedAllWorkersFilter`." If you want to explicitly restrict to currently active employees only, use `isActive = true` in your custom query.

**Operators:** Standard WQL syntax (see [Workday WQL documentation](https://community.workday.com/articles/772538))

**Example — Import active employees:**

```sql
SELECT workdayAccount{userName1}, worker{workdayID}
FROM indexedAllWorkers
(dataSourceFilter = indexedAllWorkersFilter,
 includeSubordinateOrganizations = false,
 isActive = true)
```

**Example — Import only a specific organization:**

```sql
SELECT workdayAccount{userName1}, worker{workdayID}
FROM allWorkers
WHERE organization = "Engineering"
```

---

## Microsoft Graph (Azure AD)

Use the MS Graph filter to import users from Azure AD with OData filtering, group scoping, or both.

> **Warning**
>
> **You cannot use Group ID and OData Filter at the same time.** If you set both, ingestion will fail with an error. Use Group ID to scope by group membership. Use OData Filter to scope by user attributes. If you need both, create two separate filter entries.

> **Warning**
>
> **Specifying any attributes overrides the entire default field list.** When you specify attributes, `id` and `accountEnabled` are always included automatically, but nothing else is. Include every field you need explicitly.

| Field                  | Description                                                                      | Example                                                       |
| ---------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Azure AD Group ID**  | Azure AD Object ID of the group to import from. Leave empty to import all users. | `a1b2c3d4-e5f6-7890-abcd-ef1234567890`                        |
| **OData Filter Query** | OData v4.0 filter expression. Leave empty to import all enabled users.           | `department eq 'Engineering'`                                 |
| **Attributes**         | Fields to import. Leave empty to return all available fields.                    | `mail, displayName, givenName, surname, jobTitle, department` |

**What Moveworks applies automatically:** `accountEnabled eq true` is always enforced — disabled accounts are never imported regardless of your filter. You do not need to add this yourself.

**OData operators:** `eq`, `ne`, `and`, `or`, `not`, `lt`, `le`, `gt`, `ge`, `startswith`, `endswith` (see [Microsoft Graph filter parameter docs](https://learn.microsoft.com/en-us/graph/filter-query-parameter))

**`endswith` and `startswith` requirements:** These operators require the `ConsistencyLevel: eventual` header and `$count=true` parameter. Moveworks sets both automatically — you can use `endswith` and `startswith` without any additional configuration.

**Finding your Group ID:** In the [Azure portal](https://portal.azure.com), go to Azure Active Directory → Groups → select your group → copy the **Object ID**.

**Example — Import users from a specific Azure AD group:**

```
Azure AD Group ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
OData Filter: (leave empty)
Attributes: mail, displayName, givenName, surname, jobTitle, department
```

**Example — Filter by email domain:**

```
Azure AD Group ID: (leave empty)
OData Filter: endswith(userPrincipalName, '@contoso.com')
Attributes: mail, displayName, givenName, surname, jobTitle, department, officeLocation
```

**Example — Filter by department:**

```
Azure AD Group ID: (leave empty)
OData Filter: department eq 'Engineering'
Attributes: mail, displayName, givenName, surname, jobTitle, department
```

**Example — Exclude guest accounts (members only):**

```
OData Filter: userType eq 'Member'
```

**Example — Combine conditions:**

```
OData Filter: department eq 'IT' and userType eq 'Member'
```

**Example — Multi-group import (create two separate filter entries):**

```
Entry 1 → Azure AD Group ID: <group-1-id>
Entry 2 → Azure AD Group ID: <group-2-id>
```

**Nested attributes (manager, department from a related resource):**

You can import nested fields using dot notation (e.g. `manager.displayName`). Moveworks handles the `$expand` call automatically. However, dot-notation attributes **cannot be combined with a Group ID** — this is a Microsoft Graph API limitation. Use dot-notation attributes only when Group ID is empty.

**Example — Import manager name alongside user fields:**

```
Azure AD Group ID: (leave empty)
Attributes: mail, displayName, jobTitle, department, manager.displayName, manager.mail
```

---

## SharePoint OneDrive

SharePoint OneDrive uses the same underlying Microsoft Graph API as the [MS Graph filter](#microsoft-graph-azure-ad). All MS Graph rules apply, including the Group ID + OData Filter mutual exclusivity and the `endswith`/`startswith` support.

| Field                  | Description                                        | Example                                |
| ---------------------- | -------------------------------------------------- | -------------------------------------- |
| **Azure AD Group ID**  | Group containing users. Leave empty for all users. | `a1b2c3d4-e5f6-7890-abcd-ef1234567890` |
| **OData Filter Query** | OData v4.0 filter syntax                           | `department eq 'Engineering'`          |
| **Attributes**         | Fields to import                                   | `mail, displayName, jobTitle`          |

> **Warning**
>
> **You cannot use Group ID and OData Filter at the same time** — same constraint as [MS Graph](#microsoft-graph-azure-ad). See that section for full details.

**Example — Scope to a specific group:**

```
Azure AD Group ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

**Example — Filter by domain:**

```
OData Filter: endswith(userPrincipalName, '@contoso.com')
```

---

## Salesforce

Import users from the Salesforce `User` or `Contact` table with SOQL filtering.

| Field              | Description                                               | Example                                                |
| ------------------ | --------------------------------------------------------- | ------------------------------------------------------ |
| **Table**          | `User` or `Contact`                                       | `User`                                                 |
| **SOQL Condition** | Full SOQL WHERE clause — must include the `WHERE` keyword | `WHERE IsActive = true AND Department = 'Engineering'` |
| **Attributes**     | Fields to import. Leave empty to use defaults.            | `Id, Email, FirstName, LastName, Department, Title`    |

**Default attributes (when Attributes is left empty):** `Id`, `Email`, `LastName`, `FirstName`, `Name`

> **Warning**
>
> **Specifying any attributes overrides the defaults.** If you add `Department`, you must also re-include `Id`, `Email`, `LastName`, `FirstName`, and `Name` — or those fields will not be imported.

**Default table:** `Contact`

**SOQL operators:** `=`, `!=`, `<`, `>`, `<=`, `>=`, `LIKE`, `NOT LIKE`, `IN`, `NOT IN`, `AND`, `OR`, `NOT` (see [Salesforce SOQL documentation](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm))

**Finding exact field names:** In Salesforce Setup, go to Object Manager → User (or Contact) → Fields & Relationships to see all available field API names.

**Example — Import active users only:**

```
Table: User
SOQL Condition: WHERE IsActive = true
```

**Example — Import a specific department:**

```
Table: User
SOQL Condition: WHERE IsActive = true AND Department = 'Engineering'
```

**Example — Import from a specific account (Contact table):**

```
Table: Contact
SOQL Condition: WHERE AccountId IN ('001Dn00000XXXXX', '001Dn00000YYYYY')
```

**Example — Exclude system and integration accounts:**

```
Table: User
SOQL Condition: WHERE IsActive = true AND Username NOT LIKE '%@system.com' AND UserType = 'Standard'
```

**Example — Minimal attributes for identity resolution:**

```
Table: User
SOQL Condition: WHERE IsActive = true
Attributes: Id, Email, FirstName, LastName, Name, Department, Title, ManagerId
```

---

## Exchange Online

Import mailbox users with PowerShell filtering. The filter expression is passed to the Exchange connector's PowerShell script using [Exchange Online PowerShell](https://learn.microsoft.com/en-us/powershell/exchange/exchange-online-powershell) filter syntax.

| Field                 | Description                 | Example                                       |
| --------------------- | --------------------------- | --------------------------------------------- |
| **PowerShell Filter** | PowerShell filter condition | `RecipientType -eq 'UserMailbox'`             |
| **Attributes**        | Fields to import            | `DisplayName, PrimarySmtpAddress, Department` |

**Default attributes (when Attributes is left empty):** `Identity`, `WindowsEmailAddress`, `Guid`

> **Warning**
>
> **Specifying any attributes overrides the defaults.** If you add `Department`, you must also re-include `Identity`, `WindowsEmailAddress`, and `Guid`, or those fields will not be imported.

**PowerShell operators:** `-eq`, `-ne`, `-lt`, `-gt`, `-le`, `-ge`, `-like`, `-notlike`, `-and`, `-or`, `-not` (see [Exchange Online PowerShell filter docs](https://learn.microsoft.com/en-us/powershell/exchange/filter-properties))

**Example — Import standard user mailboxes only (recommended starting point):**

```
Filter: RecipientType -eq 'UserMailbox'
```

**Example — Import users from a specific department:**

```
Filter: RecipientType -eq 'UserMailbox' -and Department -eq 'Engineering'
```

**Example — Exclude shared mailboxes and distribution lists:**

```
Filter: RecipientTypeDetails -eq 'UserMailbox'
```

**Example — Import users with a specific domain:**

```
Filter: PrimarySmtpAddress -like '*@contoso.com'
```

**Example — Minimal attributes with department:**

```
Filter: RecipientType -eq 'UserMailbox'
Attributes: Identity, WindowsEmailAddress, Guid, DisplayName, Department, Title
```

---

## Google Workspace

The Google Workspace filter imports users via the [Google Admin Directory API](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users/list). Record-level filtering is not supported — all users in the configured customer domain are returned. The only configurable option is importing additional [custom schema fields](https://developers.google.com/admin-sdk/directory/v1/guides/manage-schemas).

**Customer domain:** The customer ID used to scope the query comes from the Google Workspace connector's native configuration — it is not part of the filter. Contact your Moveworks implementation team to configure which domain is queried.

| Field              | Description                                                                                                                 | Example                    |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Custom Schemas** | Names of custom schemas to import (comma-separated). Enter the schema name only — do not include a `customSchemas.` prefix. | `EmployeeData, CostCenter` |

**Example — Import standard fields only (no filter needed):**

```
Custom Schemas: (leave empty)
```

**Example — Import with custom HR schema fields:**

```
Custom Schemas: EmployeeData, CostCenter
```

**Example — Import with multiple custom schemas:**

```
Custom Schemas: EmployeeData, LocationInfo, JobData
```

> **Info**
>
> Google Workspace does not support filtering by department, team, location, or other user attributes at the API level. To scope to a subset of users, use an Azure AD group if your org syncs Google Workspace users to Azure AD.

---

## GitHub

The GitHub filter imports members of a GitHub organization via the [GitHub REST API](https://docs.github.com/en/rest/orgs/members).

| Field                 | Description                                 | Example      |
| --------------------- | ------------------------------------------- | ------------ |
| **Organization Name** | GitHub organization slug (from the org URL) | `my-company` |

**Limitations:** No record filter or attribute selection is supported. All members of the organization are returned with default fields.

**Example — Import all members of your GitHub org:**

```
Organization Name: my-company
```

**Example — Import from multiple orgs (create one filter entry per org):**

```
Entry 1 → Organization Name: my-company
Entry 2 → Organization Name: my-company-contractors
```

---

## Confluence

The Confluence filter imports members of specific Confluence groups via the [Confluence REST API](https://developer.atlassian.com/cloud/confluence/rest/v1/intro/).

| Field        | Description                                                                     | Example                                |
| ------------ | ------------------------------------------------------------------------------- | -------------------------------------- |
| **Group ID** | Confluence group UUID to import from (Cloud only). Leave empty to use defaults. | `61fb4ba0-49fc-4300-9951-f45c00000001` |

**Default behavior (when Group ID is left empty):** Moveworks imports members from `confluence-users` and `confluence-administrators`.

**Cloud only:** Group ID requires the group's UUID (not display name). This filter type is for Confluence Cloud. For Confluence Server/on-prem, use the [Confluence Server filter](#confluence-server) instead.

**Limitations:** No OData filter or attribute selection is supported. Pagination is capped at 200 users per page (Confluence API limit).

**Finding your group UUID:** Confluence group UUIDs are not visible in the admin UI. Retrieve them via `GET /wiki/rest/api/group` — each group has an `id` field. You can also use the [Confluence API browser](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-group/).

**Example — Import a specific group by UUID:**

```
Group ID: 61fb4ba0-49fc-4300-9951-f45c00000001
```

**Example — Import multiple groups (comma-separated in a single field):**

```
Group ID: 61fb4ba0-49fc-4300-9951-f45c00000001, 71gc5cb1-50gd-5411-aa62-g56d11111112
```

---

## Confluence Server

Use the Confluence Server filter for on-premise Confluence deployments. It uses group **names** (not UUIDs) and has its own separate filter type from the Cloud Confluence filter above.

| Field          | Description                                     | Example            |
| -------------- | ----------------------------------------------- | ------------------ |
| **Group Name** | Confluence group name(s) to import members from | `confluence-users` |

**Default behavior (when Group Name is left empty):** Moveworks imports members from `confluence-users` and `confluence-administrators`.

**Multiple groups:** Enter all group names as separate items within a single filter entry — do not create separate filter entries per group.

**Limitations:** No OData filter or attribute selection is supported.

**Example — Import a specific group by name:**

```
Group Name: engineering-team
```

---

## SharePoint Online

> **Warning**
>
> **SharePoint Online filters by site membership, not by user attributes.** This filter returns every user who has been granted access to the specified SharePoint site — it is not a way to filter employees by department, location, or profile fields. Only use this filter when site access intentionally defines who should be onboarded to Moveworks.

The SharePoint Online filter returns all users with permissions on the specified site via the SharePoint REST API (`/_api/web/siteusers`). See the [SharePoint REST API docs](https://learn.microsoft.com/en-us/sharepoint/dev/sp-add-ins/get-to-know-the-sharepoint-rest-service) for reference.

| Field     | Description                                                               | Example    |
| --------- | ------------------------------------------------------------------------- | ---------- |
| **Sites** | Site name(s) to import from — the portion of the URL path after `/sites/` | `ITPortal` |

**What Moveworks applies automatically:** Only individual users are returned — service accounts, distribution lists, and SharePoint groups are excluded automatically.

**Limitations:** No OData filter or attribute selection is supported.

**Finding site names:** In SharePoint, the site name is the segment after `/sites/` in the URL. For `https://contoso.sharepoint.com/sites/ITPortal`, enter `ITPortal`. For a subsite at `https://contoso.sharepoint.com/sites/HRPortal/Policies`, enter `HRPortal/Policies`.

> **Warning**
>
> Do **not** include the `/sites/` prefix — Moveworks adds it automatically. Entering `sites/ITPortal` will result in a broken URL.

**Example — Import users from a single site:**

```
Sites: ITPortal
```

**Example — Import from multiple sites:**

```
Sites: ITPortal, HRPortal
```

**Example — Import from a subsite:**

```
Sites: HRPortal/Policies
```

---

## Cherwell

The Cherwell filter imports user records from a specific Cherwell Business Object via the [Cherwell REST API](https://help.cherwell.com/bundle/cherwell_rest_api_10_stable/page/content/system_administration/rest_api/csm_rest_business_objects.html).

| Field                  | Description                                                              | Example                                     |
| ---------------------- | ------------------------------------------------------------------------ | ------------------------------------------- |
| **Business Object ID** | Cherwell `busObId` for the user business object                          | `9338216b3f4b2f0f1d9a2f49ac`                |
| **User Fields**        | List of Cherwell field IDs to import. At least one field ID is required. | `93d9a38a39f8a0e9a44e3c46b8, 93d9abcdef...` |

> **Warning**
>
> **User Fields uses field IDs, not field names.** Each field in Cherwell has a unique ID (a long hex string). You must use these IDs, not display names like "Email" or "FirstName". At least one field ID is required.

**Finding field IDs:** In Cherwell, open Business Object Editor for your user object → select a field → the field ID (busObRecId) is shown in the properties panel.

**Example — Import specific fields only:**

```
Business Object ID: 9338216b3f4b2f0f1d9a2f49ac
User Fields: 93d9a38a39f8a0e9a44e3c46b8, 94a3bc29ab02c1...
```

---

## FreshDesk

The FreshDesk filter controls whether agents are imported in addition to contacts. Contacts are always imported.

| Field               | Description                                           | Example  |
| ------------------- | ----------------------------------------------------- | -------- |
| **Agent Ingestion** | When enabled, imports agents in addition to contacts. | Disabled |

**Default behavior:** Contacts only. Enabling **Agent Ingestion** adds agents to the import — it does not replace contacts.

**Limitations:** No record-level filter or attribute selection is supported. Agent ingestion requires the FreshDesk connector to be authenticated with agent admin privileges.

**Example — Import contacts only (default):**

```
Agent Ingestion: disabled
```

**Example — Import contacts and agents:**

```
Agent Ingestion: enabled
```

---

## Troubleshooting

**No users imported after adding a filter**

* Start with no filter, verify that users import, then add the filter incrementally
* Verify the query string against your source system's API directly (e.g. run an OData query in [Microsoft Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer))
* Check that any Group ID, org name, or site name is spelled exactly correctly
* For Azure AD: confirm the Group ID is the Object ID, not the display name (see [Finding your Group ID](#microsoft-graph-azure-ad))

**Fields missing from user profiles after specifying attributes**

* You added at least one attribute but forgot to re-include the fields you already had — see the [attribute override warning](#overview)
* Check exact field API names in your source system (case-sensitive in all sources)
* For Azure AD: `id` and `accountEnabled` are always included automatically — do not worry about those

**Error: "MSGraph API does not support combining $filter and $expand parameters"**

* You have a Group ID, dot-notation attributes (e.g. `manager.displayName`), and an OData Filter all on the same entry — this combination is not supported
* Remove the OData Filter from that entry, or move the dot-notation attributes to a separate entry without Group ID

**Error: "Multiple expand fields detected"**

* You included dot-notation attributes from two different parent resources (e.g. `manager.displayName` and `department.name`)
* MS Graph only supports expanding one parent resource per request — remove the second dot-notation attribute or create a separate filter entry

**Duplicate users when using multiple filter entries**

* Expected behavior — multiple filters create a union, and the same user may appear in more than one group
* Moveworks deduplicates by user ID automatically; this does not create duplicate user records

**Workday filter string has no effect**

* Your org may be in REST mode, which does not support filter strings — see the [Workday section](#workday)
* Contact your Moveworks implementation team to check whether WQL mode is enabled

**Okta filter returns fewer users than expected**

* Verify you are not accidentally excluding `RECOVERY` or `PASSWORD_EXPIRED` users who should be imported
* The base filter already includes all active statuses; your query string narrows from that set — see [Okta](#okta)

**Confluence Group ID is not working**

* The Group ID must be the group's UUID, not the display name — see [Finding your group UUID](#confluence)
* For on-premise Confluence, use the [Confluence Server filter](#confluence-server) instead, which accepts group names

---

## Filter Syntax Reference

### OData v4.0 — Azure AD / Microsoft Graph / SharePoint OneDrive

**Documentation:** [Microsoft Graph filter parameter](https://learn.microsoft.com/en-us/graph/filter-query-parameter) · [OData query parameters](https://learn.microsoft.com/en-us/graph/query-parameters)

| Operator     | Meaning          | Example                                             |
| ------------ | ---------------- | --------------------------------------------------- |
| `eq`         | Equals           | `department eq 'Engineering'`                       |
| `ne`         | Not equals       | `userType ne 'Guest'`                               |
| `startswith` | Starts with      | `startswith(displayName, 'John')`                   |
| `endswith`   | Ends with        | `endswith(userPrincipalName, '@contoso.com')`       |
| `and`        | Both conditions  | `department eq 'IT' and userType eq 'Member'`       |
| `or`         | Either condition | `department eq 'IT' or department eq 'Engineering'` |
| `not`        | Negation         | `not (userType eq 'Guest')`                         |

All operators are **lowercase**. String values use **single quotes**.

`startswith` and `endswith` require `ConsistencyLevel: eventual` — Moveworks sets this automatically.

---

### SOQL — Salesforce

**Documentation:** [Salesforce SOQL and SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm)

The entire value of the SOQL Condition field is appended to `SELECT ... FROM {table}` — it must include the `WHERE` keyword.

| Operator   | Meaning          | Full condition example                                  |
| ---------- | ---------------- | ------------------------------------------------------- |
| `=`        | Equals           | `WHERE IsActive = true`                                 |
| `!=`       | Not equals       | `WHERE UserType != 'Guest'`                             |
| `LIKE`     | Pattern match    | `WHERE Username LIKE '%@contoso.com'`                   |
| `NOT LIKE` | Negative pattern | `WHERE Username NOT LIKE '%@system.com'`                |
| `IN`       | Match list       | `WHERE Department IN ('IT', 'Engineering')`             |
| `AND`      | Both conditions  | `WHERE IsActive = true AND Department = 'IT'`           |
| `OR`       | Either condition | `WHERE Department = 'IT' OR Department = 'Engineering'` |

All operators are **uppercase**. String values use **single quotes**.

---

### ServiceNow Encoded Query

**Documentation:** [ServiceNow Encoded Query Strings](https://developer.servicenow.com/dev.do#!/guides/sandiego/now-platform/tpb-guide/encoded_query_strings)

| Operator     | Meaning     | Example                                  |
| ------------ | ----------- | ---------------------------------------- |
| `=`          | Equals      | `department=Engineering`                 |
| `!=`         | Not equals  | `title!=Contractor`                      |
| `^`          | AND         | `department=IT^title=Engineer`           |
| `^OR`        | OR          | `department=IT^ORdepartment=Engineering` |
| `LIKE`       | Contains    | `user_nameLIKEjohn`                      |
| `STARTSWITH` | Starts with | `user_nameSTARTSWITHjohn`                |
| `ENDSWITH`   | Ends with   | `emailENDSWITH@contoso.com`              |

`active=true` is prepended automatically — do not add it yourself.

---

### PowerShell — Exchange Online

**Documentation:** [Exchange Online PowerShell filterable properties](https://learn.microsoft.com/en-us/powershell/exchange/filter-properties)

| Operator   | Meaning          | Example                                                    |
| ---------- | ---------------- | ---------------------------------------------------------- |
| `-eq`      | Equals           | `RecipientType -eq 'UserMailbox'`                          |
| `-ne`      | Not equals       | `RecipientType -ne 'SharedMailbox'`                        |
| `-like`    | Pattern match    | `PrimarySmtpAddress -like '*@contoso.com'`                 |
| `-notlike` | Negative pattern | `PrimarySmtpAddress -notlike '*@system.com'`               |
| `-and`     | Both conditions  | `RecipientType -eq 'UserMailbox' -and Department -eq 'IT'` |
| `-or`      | Either condition | `Department -eq 'IT' -or Department -eq 'Engineering'`     |

All operators are **prefixed with `-`** (PowerShell convention). String values use **single quotes**.

---

## Limitations

* **[MS Graph](#microsoft-graph-azure-ad) and [SharePoint OneDrive](#sharepoint-onedrive): Group ID and OData Filter cannot be combined** on the same filter entry — use separate entries if you need both group scoping and attribute filtering
* **[MS Graph](#microsoft-graph-azure-ad): Dot-notation attributes cannot be combined with Group ID** — only one parent resource can be expanded per request
* **Specifying any attributes overrides the complete default field list** across all sources — always re-include every field you need, not just the new one
* **[Salesforce](#salesforce): SOQL Condition must include the `WHERE` keyword** — the condition is appended directly to the SOQL query string
* **[Workday](#workday): Filter string replaces the entire default query** (WQL mode only) — write a complete WQL SELECT statement, not a condition fragment
* **[Workday](#workday): Filter strings are silently ignored in REST mode** — contact your implementation team to confirm WQL mode is enabled
* **[Confluence](#confluence): Group ID requires a UUID** (Cloud only) — display names are not accepted; for on-premise use the [Confluence Server filter](#confluence-server) with group names
* **[Confluence](#confluence): Pagination is capped at 200 users per page** — Confluence API limit
* **[SharePoint Online](#sharepoint-online): Filters by site membership, not user attributes** — returns all users with site access; no attribute-level filtering is available
* **[FreshDesk](#freshdesk): No attribute selection or record filtering** — only the endpoint (contacts vs. agents) is configurable
* **[Google Workspace](#google-workspace): No record filtering** — all users in the customer domain are returned; user-attribute filtering is not supported at the API level
* **Multiple filter entries are unioned** — users appearing in more than one filter are deduplicated by ID automatically
* **Attribute field names are case-sensitive** and must match the exact API field name for the source system