# Synchronize Users from Google Workspace to Cloud Voice

Once Cloud Voice is connected to Google Workspace, the next step is to bring your Google users into the phone system and give each of them an extension. Cloud Voice lets you decide exactly which users to synchronize and how their extension numbers are assigned, so you can onboard your whole directory or just a subset of it.

## Before you start

A few things to know before you configure synchronization:

- **How many users you can sync.** The number of Google users you can bring in is capped by how many extensions your Cloud Voice system is able to create. If you run out of extension capacity, not every user will sync.
- **Which users you can sync.** Cloud Voice supports four synchronization scopes. Pick the one that matches how you want to onboard your directory.

| Scope | What it covers | How extensions are handled |
| --- | --- | --- |
| All users | Every user in the organization, regardless of account status. | Extensions are created and linked automatically using your assignment rule. |
| Users in a specific organizational unit | Users in one or more organizational units, excluding deleted users. | Extensions are created and linked automatically using your assignment rule. |
| Users in a specific group | Users in one or more groups, excluding deleted users. | Extensions are created and linked automatically using your assignment rule. |
| Specific users | Users you select by hand, excluding archived and deleted users. | You assign an existing extension to each user yourself. |

:::caution
The **Specific users** scope links people to extensions you already have. Create those extensions before you set up synchronization.
:::

## Open the User Synchronization settings

Every procedure below starts from the same place.

1. Sign in to the Cloud Voice web portal and go to **Integrations > Collaboration**.
2. Scroll down to the **User Synchronization** section.

![Cloud Voice, the User Synchronization section on the Collaboration integration page](/images/pbx/google-user-sync.png)

The fields shown in this section change based on what you choose in the **User Range for Extension Auto Creation** drop-down list. The procedures that follow walk through each range.

## Settings you'll reuse

The scopes share most of the same options. Here's what each one does; the individual procedures tell you which apply.

**User's Extension Number**: controls how Cloud Voice picks an extension number when it creates extensions automatically.

| Rule | What it does |
| --- | --- |
| Assign Automatically | Numbers extensions in sequence from a value you choose. Enter that value in **Start Extension Number from**. |
| Read Specific Property Value | Takes the extension number from a Google user account property. Enter the property in **Property Name**: for example, `externalIds.#(type=="organization").value`. |

**Delete the Extension when its associated user account is**: select one or more Google account statuses. When a synced user reaches any of them, Cloud Voice stops syncing that user and removes their extension.

**Auto associate Extensions with the Users that share the same email address**: decides what happens when a Google user's **Primary email** matches the **Email Address** of an extension that already exists in Cloud Voice.

- Selected: the user is synced and tied to the existing extension, and that extension's user details are overwritten with the values from Google.
- Cleared: the user is not synced, because Cloud Voice does not allow two extensions to share an email address.

**Auto delete the Extensions no longer in sync**: when selected, extensions belonging to users that fall outside the current scope are removed automatically. This keeps unused extensions from piling up when you narrow the synchronization scope.

:::caution
Both **Delete the Extension when its associated user account is** and **Auto delete the Extensions no longer in sync** remove extensions automatically, without a further prompt. Deleting an extension takes away that person's phone service: they can no longer make or take calls until they are synced again. Choose these settings deliberately.
:::

**Send Welcome Email automatically after an extension is created**: select this to email each newly synced user their Cloud Voice App welcome message.

**Map**: choose which Google user fields to carry into Cloud Voice and pair each one with its matching extension field. See Google's [Google Workspace user property reference](https://developers.google.com/workspace/admin/directory/reference/rest/v1/users#username) for the field names to enter.

:::note
On synced extensions, the **First Name**, **Last Name**, **Email Address**, **Mobile Number**, and **Job Title** are owned by Google. You can only change them in Google Workspace, and the updates flow into Cloud Voice on the next synchronization.
:::

## Synchronize all users

1. In the **User Range for Extension Auto Creation** drop-down list, select **All Users**.

   ![The User Range drop-down set to All Users](/images/pbx/google-sync-all-user.png)

2. Set the extension assignment options that decide how synced users are matched to extensions.

   ![The extension assignment options for automatically created extensions](/images/pbx/google-extension-assignment.png)

   1. Choose a rule in the **User's Extension Number** drop-down list.
   2. In the **Delete the Extension when its associated user account is** drop-down list, select the account statuses that should trigger removal.

      ![The account-status drop-down that controls when an extension is deleted](/images/pbx/goolge-delete-ext-status.png)

   3. Set **Auto associate Extensions with the Users that share the same email address** to match how you want to handle users whose email already exists on an extension.

3. To email new users their Cloud Voice App details, select **Send Welcome Email automatically after an extension is created**.
4. **Optional:** In the **Map** section, pick and pair the user fields you want to synchronize.

   ![The Map section pairing Google fields with Cloud Voice fields](/images/pbx/google-sso-map.png)

5. Click **Save**.

Cloud Voice runs the first synchronization right away. A banner reports the result, and every user is synced and given an extension under **Extension and Trunk > Extension**.

![The banner confirming that all users were synchronized](/images/pbx/google-sync-all-result.png)

Synced extensions are flagged with a Google marker ![Google marker](/images/pbx/google.png) and cannot be deleted from Cloud Voice.

![Cloud Voice, the extension list showing Google-synced extensions marked with the Google icon](/images/pbx/google-sync-extension.png)

## Synchronize users in a specific organizational unit

1. Point Cloud Voice at the organizational units you want to sync.

   ![The User Range set to a specific organizational unit with units selected](/images/pbx/google-sync-ou-user.png)

   1. In the **User Range for Extension Auto Creation** drop-down list, select **Users in Specific Organizational Unit**.
   2. In the **Organizational Units** drop-down list, choose one or more units.

2. Set the extension assignment options.

   1. To have Cloud Voice remove extensions for users that later fall out of scope, select **Auto delete the Extensions no longer in sync**.
   2. Choose a rule in the **User's Extension Number** drop-down list.
   3. In the **Delete the Extension when its associated user account is** drop-down list, select the account statuses that should trigger removal.

      ![The account-status drop-down that controls when an extension is deleted](/images/pbx/goolge-delete-ext-status.png)

   4. Set **Auto associate Extensions with the Users that share the same email address** as needed.

3. To email new users their Cloud Voice App details, select **Send Welcome Email automatically after an extension is created**.
4. **Optional:** In the **Map** section, pick and pair the user fields you want to synchronize.
5. Click **Save**.

Cloud Voice runs the first synchronization right away and shows a result banner.

![The banner confirming that the organizational unit was synchronized](/images/pbx/google-sync-ou-result.png)

Users from the selected units are synced and given extensions under **Extension and Trunk > Extension**, each flagged with a Google marker ![Google marker](/images/pbx/google.png) and locked against deletion in Cloud Voice.

## Synchronize users in a specific group

1. Point Cloud Voice at the groups you want to sync.

   ![The User Range set to a specific group with groups selected](/images/pbx/google-sync-group-user.png)

   1. In the **User Range for Extension Auto Creation** drop-down list, select **Users in Specific Group**.
   2. In the **Group** drop-down list, choose one or more groups.

2. Set the extension assignment options.

   1. To have Cloud Voice remove extensions for users that later fall out of scope, select **Auto delete the Extensions no longer in sync**.
   2. Choose a rule in the **User's Extension Number** drop-down list.
   3. In the **Delete the Extension when its associated user account is** drop-down list, select the account statuses that should trigger removal.
   4. Set **Auto associate Extensions with the Users that share the same email address** as needed.

3. To email new users their Cloud Voice App details, select **Send Welcome Email automatically after an extension is created**.
4. **Optional:** In the **Map** section, pick and pair the user fields you want to synchronize.
5. Click **Save**.

Cloud Voice runs the first synchronization right away and shows a result banner. Users from the selected groups are synced and given extensions under **Extension and Trunk > Extension**, each flagged with a Google marker ![Google marker](/images/pbx/google.png) and locked against deletion in Cloud Voice.

## Synchronize specific users

Use this scope when you want to hand-pick users and tie each one to an extension you've already created.

1. In the **User Range for Extension Auto Creation** drop-down list, select **Specific Users**.

   ![The User Range set to Specific Users with search and selection controls](/images/pbx/google-sync-specific-user.png)

2. In the **Search Criteria** drop-down list, choose whether to search by organizational unit or by group, specify the unit or group, then click **Search Users**. Matching users appear in the results.
3. In the **Search Result List**, select the users you want and click **Synchronize to Cloud Voice**.
4. In the **Synchronization List**, choose an extension from the drop-down list for each user to link them together.

   :::note
   To drop a user you no longer want to sync, disassociate them in the list.

   ![Disassociating a selected Google user from the synchronization list](/images/pbx/google-disassociate.png)
   :::

5. Set the extension management options that decide how these extensions are handled when the scope or a user's account status changes.

   ![The extension management options for hand-selected users](/images/pbx/google-ext-mgt.png)

   1. To have Cloud Voice remove extensions for users that later fall out of scope, select **Auto delete the Extensions no longer in sync**.
   2. In the **Delete the Extension when its associated user account is** drop-down list, select the account statuses that should trigger removal.

6. To email new users their Cloud Voice App details, select **Send Welcome Email automatically after an extension is created**.
7. **Optional:** In the **Map** section, pick and pair the user fields you want to synchronize.
8. Click **Save**.

Cloud Voice runs the first synchronization right away and shows a result banner. The selected users are synced and given their assigned extensions under **Extension and Trunk > Extension**, each flagged with a Google marker ![Google marker](/images/pbx/google.png) and locked against deletion in Cloud Voice.

## What to do next

To let synced users open the Cloud Voice App with their Google credentials, turn on Single Sign-on. See [Allow Users to Log in to the Cloud Voice App with Google SSO](/pbx/integrations/google-workspace/allow-users-to-log-in-to-cloud-voice-app-uc-clients-with-google-sso/).