Migrate Chat apps shared in your domain after merging Google Workspace organizations

If your Google Workspace organization or domain merges with another one, your Google Chat apps might stop responding, disappear from direct messages and Chat rooms, or otherwise stop working as expected. Mergers don't always affect Chat apps, and your Chat app might remain fully functional, especially if you published it on the Google Workspace Marketplace or created it as a member of the destination environment; the Google Workspace organization or domain that other organizations or domains merge into. If your Chat app is affected by the merge, then to ensure a fully functional Chat app, migrate it to a new Google Cloud project.

NOTE: When your Google Workspace domain merges or changes, you receive an email saying that your organization has (or will soon have) a new domain administrator. For more information, refer to My Google Account is now managed by an administrator.

Does your Chat app require migration?

If any of the following conditions are true, then your Chat app might remain fully functional with no need to migrate:

• Your Chat app is published on the Marketplace.
• You, the Chat app developer, were a member of the destination environment when you first saved your Chat app configuration.
• Your Chat app is only shared with specific users via their email addresses, and users' email addresses remain the same after the merge.

Whether or not you have to migrate your Chat app is determined by how you publish your Chat app and by administrative settings in the merged Google Workspace organization that might cause your Chat app to stop working. For example, the administrator of the merged Google Workspace organization might have to add your Chat app to an allowlist, or might have to allow users to install Chat app. For more information, see Allow users to install apps in the Google Workspace admin help.

Before migrating your Chat app, check with your organization’s admin to see if administrative settings are affecting it. Changing an administrative setting might restore full functionality to your Chat app and make migration unnecessary.

What happens to Chat apps after the merge?

To ensure that your Chat app does not respond to users who shouldn't have permission to message it, access to your app remains limited to the domain or organization under which it was created.

If you were a member of the destination environment when you first saved your Chat app configuration, then your Chat app continues to work as expected.

If you were a member of a source environment when you first saved your Chat app, then whether people retain or lose access to your Chat app is determined by how the Chat app is shared:

• If your Chat app is shared with Everyone in your domain, then after merging, users who are now part of the destination environment lose access to your Chat app.
• If your Chat app is shared with both specific users and groups, then after merging, the specific users retain access to the Chat app, but the groups lose access.

To allow groups or the entire domain to message your Chat app, migrate the Chat app and set the appropriate permissions on the Google Chat API Configuration page in Google Cloud console.

Migrate your Chat app

Migrating your Chat app is a three-step process.

1. Create a Google Cloud project in the destination environment and enable APIs.
2. Redeploy your Chat app from the new Cloud project.
3. Add the recreated Chat app to Chat rooms or conversations, and disable the original app.

BEST PRACTICE: Before migrating your Chat app, check with your destination environment’s admin to see if administrative settings are affecting it. Changing an administrative setting might restore full functionality to your Chat app and make migration unnecessary. For example, your Google Workspace admin might have to add your Chat app to an allowlist, or might have to allow users to install Chat apps.

Step 1: Create a Cloud project in the destination environment and enable APIs

Creating a new Cloud project for the migrated Chat app in the merged Google Workspace organization ensures that users and groups who you let access the Chat app can do so without error.

1. Open the Google Cloud console.
2. Next to "({gcp_name}}," click the Down arrow . A dialog listing current projects appears.
3. Click New Project. The New Project screen appears.
4. In the Project Name field, enter a descriptive name for your project.
5. (Optional) To edit the Project ID, click Edit. The project ID can't be changed after the project is created, so choose an ID that meets your needs for the lifetime of the project.
6. Click Organization and select your organization.
7. In the Location field, click Browse to display potential locations for your project.
8. Click a location and click Select.
9. Click Create. The console navigates to the Dashboard page and your project is created within a few minutes.

After creating the project, you’re ready to enable the APIs your Chat app uses to run. All Chat app require “Google Chat API”. Depending on how your Chat app is built, you might need to enable other APIs. For example, if your Chat app uses Google Cloud Functions, enable “Cloud Functions API” and “Cloud Build API”. As a best practice, to ensure that the migrated app works without error, enable the same APIs in the new project that are enabled in the old project.

To enable an API:

1. Open the Google Cloud console.
2. Next to "Google Cloud," click the Down arrow and select your new project.
3. In the top-left corner, click Menu > APIs & Services.
4. Click Enable APIs and Services. The Welcome to API Library page appears.
5. In the search field, enter the name of the API you want to enable. For example, type “Google Chat API” to find the Google Chat API.
6. Click the API to enable. The API page appears.
7. Click Enable. The Overview page appears.
8. To enable an additional API, repeat steps 3 - 7.

It might be necessary to configure the OAuth consent screen for your Cloud project. To configure the OAuth consent screen, refer to Setting up OAuth 2.0. If your Chat app uses a service account, it might be helpful to refer to Use service accounts.

For further information on Google Cloud projects, refer to Creating and managing projects.

Step 2: Redeploy your Chat app from the new Cloud project

Depending on whether your Chat app is built with Apps Script or another language, like Python or Java, redeploying your Chat app differs a little. In either case, you don’t need to recreate all of your code.

Redeploy a Chat app

To redeploy your Chat app, specify the correct configuration in your new Google Cloud project.

1. Open the Google Cloud console.
2. Next to "Google Cloud," click the Down arrow and select your new project.
3. In the search field, enter the name of the API you want to enable. For example, type “Google Chat API” to find the Google Chat API.
4. Click Manage.
5. Click Configuration.
6. Complete the configuration form. For help completing the configuration form, refer to About app configuration.
7. Click Save.

IMPORTANT: If your Chat app uses a service account to make calls to Google APIs, update the Chat app’s service account details. For help updating your Chat app’s service account, refer to Use service accounts.

Redeploy an Apps Script Chat app

To redeploy your Apps Script Chat app, change the Google Cloud project number its Apps Script project is associated with to the one belonging to your new Google Cloud project. Then, copy your Apps Script deployment ID and paste it into the Chat app configuration page in Google Cloud console.

Copy your Cloud project number

1. Open the Google Cloud console.
2. Next to "Google Cloud," click the Down arrow and select your new project.
3. In the top-left corner, click Menu > IAM & Admin > Manage Resources.
4. Find your new project in the listed projects. In the filter bar, enter the name of your new project and press enter.
5. Next to your project, click More options > Settings.
6. Under “Project number”, copy the project number.

Switch your Apps Script project's Cloud project

1. Go to script.google.com.
2. In the search bar, search for your Chat app’s Apps Script project.
3. Click the Apps Script project.
4. Click Project Settings .
5. Under Google Cloud (GCP) Project, click Change project.
6. In Google Cloud project number, enter the Google Cloud project number.
7. Click Set project.

Copy your Apps Script project's deployment ID

1. In the top-right, click Deploy > Manage deployments.
2. Under Deployment ID, click Copy.
3. Click Done.

Reconfigure and redploy your Chat app

1. Open the Google Cloud console.
2. Next to "Google Cloud," click the Down arrow and select your new project.
3. In the search field, search for “Google Chat API” and click Google Chat API.
4. Click Manage.
5. Click Configuration.
6. Under Connection settings, select Apps Script project.
7. In the Deployment ID field, paste the deployment id.
8. Complete the configuration form. For help completing the configuration form, refer to About app configuration.
9. Click Save.

Before your Chat app becomes available to users in the destination environment, your administrator might have to manually allow the Chat app. For more information, refer to Share your app only in your domain.

Step 3: Add the recreated Chat app to Chat rooms or conversations, and disable the original app

Now that the Chat app is migrated to the destination environment, it's time to publicize it. Add it into Chat rooms or conversations and remove the old app from them so that people only message the migrated app.

BEST PRACTICE:To aid adoption of the migrated Chat app, announce the migration to your colleagues and encourage them to install the migrated app in Chat rooms and conversations.

First, add the migrated app to rooms or conversations:

1. Go to Chat or Gmail.
2. Select a conversation or room.
   • If the conversation window is expanded, at the top, click the drop-down next to the name of the room or person.
   • If the conversation window is minimized, click More options .
3. Click Add people & apps.
4. Choose an option:
   • Enter the name of the app.
   • Search to find the app.
5. Click Send.
6. Repeat steps 2 - 5 for multiple Chat conversations and rooms, as necessary.

Next, remove the old app from rooms or conversations:

1. Go to Chat or your Gmail account.
2. Select a conversation or room.
   • If the conversation window is expanded, at the top, click the drop-down next to the name of the room or person.
   • If the conversation window is minimized, click More options .
3. Click View members.
4. Point to the old, un-migrated Chat app and click More options > Remove from room.
5. Repeat steps 2 - 4 for multiple {chat_name_short} conversations and rooms, as necessary.

For further information about adding and removing apps, refer to Get started with apps in Google Chat.

Finally, disable the original app to encourage people to replace it with the new one:

1. Open the Google Cloud console.
2. If necessary, select the Cloud project that hosts the original, non-migrated Chat app.
   1. Next to "Google Cloud," click the Down arrow . A dialog listing current projects appears.
   2. Select the project that hosts the migrated Chat app.
   3. Click Open.
3. In the search field, enter "Google Chat API" and click Google Chat API.
4. Click Manage.
5. Click Configuration.
6. In the "App status" section, select Disabled.
7. Click Save.

Further reading

As you migrate your Chat app, it may be helpful to refer to the following:

• Chat app concepts
• Create apps
• Develop Apps Script apps
• Publish apps
• Setting up OAuth 2.0
• Use service accounts