> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync groups

> Turn on group sync to bring a directory's groups and their membership into Iru Identity, and keep them up to date on every sync.

Group sync brings a directory's groups and their membership into Iru and keeps them up to date on every sync.

Group sync is available only for **Google Workspace**. Google Workspace sends its groups, and each group's list of members, so Iru can create a matching group for each one. **Workday** and **BambooHR** do not send groups or group membership. They send only fields about each person, such as department or location, so there are no groups to bring in. To group people by those fields, use an [Auto Group](https://docs.iru.com/en/identity/directory/auto-groups.md) instead.

Directory sync always brings users into Iru. Group sync also brings in the groups those users belong to. Iru creates a matching group for each group in the directory, keeps its members in step with the directory, and updates it on the connection's sync schedule. You can then use these groups anywhere you use groups in Iru, such as giving a group access to an application.

Group sync is off by default. Users keep syncing whether or not it is on.

> [!NOTE]
>
> For how a Google Workspace connection is created, see [Connect Google Workspace](https://docs.iru.com/en/identity/directory/google-workspace.md). For concepts shared across every provider, see [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync).

## Turn on group sync

**1. Open the Google Workspace connection**

In **Directory → Sync**, open your Google Workspace connection.

**2. Edit the configuration**

Select **Edit**. On the **Configuration** tab, under **Groups**, set **Group sync** to **Sync groups and membership**.

**3. Exclude groups you don't need**

Optionally, add an **Exclude group IQL expression** to skip groups you don't want in Iru. See [Exclude group IQL expression](#exclude-group-iql-expression).

**4. Save**

Select **Save**. Groups appear after the next sync. To sync right away, open the **Sync** tab and select **Sync now**.

If you connected Google Workspace before group sync was available, reconnect the connection first. Group sync needs read access to groups, which older connections did not request.

## Settings

### Group sync

**Group sync** controls whether this connection brings in groups.

* **Don't sync groups**: Iru syncs users only.
* **Sync groups and membership**: Iru syncs users, groups, and each group's members.

### Exclude group IQL expression

The **Exclude group IQL expression** skips every group the expression matches. Leave it empty to sync every group. The expression can use two fields:

* **name**: the group's name.
* **memberCount**: how many direct members the group has.

For example, `memberCount < 2 || name.startsWith("test-")` skips groups with fewer than two members and groups whose names start with `test-`. See [IQL expressions](https://docs.iru.com/en/identity/getting-started/iql-expressions.md).

## Review the groups Iru finds

Open the connection, go to the **Sync** tab, and select **Review Groups**. This list shows every group the directory reports, including the ones Iru is not syncing, so you can check the exclusion expression against real groups.

| Status | What it means |
| - | - |
| **Synced** | Iru keeps this group and its members up to date. |
| **Pending first sync** | Iru will sync this group but has not applied it yet. |
| **Excluded by filter** | The **Exclude group IQL expression** matches this group. Edit the expression to include it again. |
| **Ignored** | Someone chose not to sync this group. Select **Sync this group** in the row menu to start syncing it again. |

From a group's row menu:

* **Ignore** stops syncing the group. If it already synced, it stays in Iru with its current members and access, and you manage it like any other group.
* **Sync this group** makes the directory the source of truth again. The directory's members replace the group's members in Iru, so anyone added by hand is removed, along with any access they had through the group.
* **Delete group from Iru** appears once Iru has stopped syncing a group it created. Deleting removes the group and its members from Iru and cannot be undone. Members lose any access they had through the group. If you later select **Sync this group** and the directory still reports the group, it comes back on the next sync.

## See the groups in Iru

The **Effective Groups** tab lists the groups this connection has created in Iru.

* **Synced**: Iru keeps this group and its members up to date.
* **Not in source**: the directory stopped reporting this group. It was deleted there, filtered out, or the connection was removed. Iru keeps the group and its members as they were, stops syncing it, and hands it to you to manage.

## Considerations

> [accordion] Your directory owns synced groups
>
> While Iru syncs a group, the directory decides its name and its members. You can't rename a synced group or change its members in Iru. Make those changes in Google Workspace, and they appear in Iru on the next sync. You can still use the group across Iru, for example to give its members access to applications.

> [accordion] Sync never deletes groups
>
> When the directory stops reporting a group, Iru does not delete it. The group gets the **Not in source** badge, keeps its members and access, and becomes yours to manage or delete.

> [accordion] Only synced users become members
>
> Iru adds a member to a group only if that person is a user this connection syncs. Members outside your Google Workspace domain, such as personal email addresses, are skipped. So is Google's "all users in the organization" membership. If you limit the sync with an **Org unit path**, people outside that org unit are not added to groups either.

> [accordion] Nested groups carry over
>
> When a Google group contains another group, Iru keeps that nesting between the synced groups.

> [accordion] A sync applies groups only when it reads them all
>
> Iru reads every group and every member before it changes anything. If a sync stops partway, Iru does not treat the groups it did not reach as removed.

> [accordion] Large directories take longer to sync
>
> Iru reads each group's members separately, so syncs take longer as the number of groups grows. Excluding groups you don't need keeps syncs faster.

## Best practices

**1. Start with an exclusion expression**

Skip test groups, mailing lists, and very small groups before the first sync, so only groups you plan to use reach Iru.

**2. Check Review Groups before relying on a group**

Confirm a group shows **Synced** before you give it access to an application.

**3. Make membership changes in Google Workspace**

Iru follows the directory, so changes made there are the ones that last.

**4. Ignore a group instead of deleting it**

Ignoring keeps the group and its access in Iru while you decide what to do with it.

## Troubleshooting

> [accordion] Groups don't appear after turning on group sync
>
> **Possible causes:**
>
> * No sync has run since you turned on group sync.
> * The connection was made before group sync was available and can't read groups.
> * The **Exclude group IQL expression** matches the groups.
>
> **Solutions:**
>
> * Select **Sync now**, then check **Review Groups**.
> * Reconnect the Google Workspace connection.
> * Check the group's status on **Review Groups**. If it shows **Excluded by filter**, edit the expression.

> [accordion] A group is missing members
>
> **Possible causes:**
>
> * The missing people are not users this connection syncs, for example because they are outside the **Org unit path**.
> * The missing people are outside your Google Workspace domain.
>
> **Solutions:**
>
> * Check that each missing person appears on the **Effective Users** tab.
> * Widen or clear the **Org unit path** if they should be synced.

> [accordion] You can't edit a group's members
>
> **Possible causes:**
>
> * Iru syncs the group from the directory.
>
> **Solutions:**
>
> * Change the members in Google Workspace and select **Sync now**.
> * To manage the group in Iru instead, select **Ignore** on **Review Groups**.

## Related Articles

> [card] [Connect Google Workspace](https://docs.iru.com/en/identity/directory/google-workspace.md)
>
> Connect Google Workspace so Iru can read users and, optionally, groups.

> [card] [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync)
>
> The shared concepts behind every Directory Sync provider.

> [card] [Auto Groups](https://docs.iru.com/en/identity/directory/auto-groups.md)
>
> Group people by a profile attribute when the source does not send groups.

> [card] [Groups](https://docs.iru.com/en/identity/directory/groups)
>
> How manual, built-in, and auto groups assign access in Iru Identity.


## Related topics

- [Connect Google Workspace](https://docs.iru.com/en/identity/directory/google-workspace.md)
- [Groups](https://docs.iru.com/en/identity/directory/groups.md)
- [Directory Sync](https://docs.iru.com/en/identity/directory/directory-sync.md)
