Upgrade legacy Gmail and Calendar add-ons

If you've already built and published an add-on to extend Gmail or Calendar, you can upgrade it into a Google Workspace add-on. The instructions in this page detail how to add Google Workspace functionality to your existing Gmail or Calendar add-ons and then publish your upgraded add-on so it can be discovered and installed.

You can transfer the new functionality into your original add-on to retain your Google Workspace Marketplace listing, installs, and users. Upgrading also allows you to take advantage of new Google Workspace add-on features such as homepages.

Step 1: Make a copy of your add-on's Apps Script project

Your upgraded add-on uses the same Google Cloud project as your published add-on, but it's important to create and use a copy of the underlying Apps Script project so that your existing users aren't affected while you're testing the upgraded version. Upgrading a copy of the original script project also means you can always access the original code, and can redeploy it later if necessary.

Open your existing Gmail add-on or Calendar conferencing add-on Apps Script project.
At the left, click Overview .
At the right, click Make a copy .
At the left, click Project Settings > Change project.
Click GCP Project Number.
Enter the same project number associated with your existing, published add-on Apps Script project.
Click Set project.

Step 2: Integrate Google Workspace add-on

You must design and implement any Google Workspace add-on features you want to add to your add-on.

Plan what content to show in your add-on's homepage cards and whether they should appear in Gmail, Calendar, Drive, or any combination of the three hosts. If you want a homepage in more than one host, decide whether if it can be the same homepage or if you want custom homepage cards for each host.
In your copied add-on Apps Script project, build your homepage cards with homepageTrigger functions. Make sure to include any supporting functions or logic needed to control your new homepage interfaces.
Consider adding contextual cards triggered by a user's action, like opening a Gmail message thread or Calendar event.

Caution: Upgraded add-ons receive a different ID value for Gmail messages than Gmail add-ons receive. This change only affects upgraded add-ons that use messageId as a key in any permanent storage. If needed, you can still get the old ID values with the Gmail API. The Gmail API's messages().get() method accepts both new and old ID values, but only returns the old ID values.
Update any accessing of event objects in your add-on (in widget callback functions or in contextual trigger functions) to use the updated event object structure. The new structure still contains the same event object fields used by Gmail and Calendar conferencing add-ons, but those original fields are deprecated and will eventually be removed.

Step 3: Update your add-on's manifest

The way in which configuration information is stored in the manifest structure of Google Workspace add-ons has changed considerably from the structure Gmail add-ons and Calendar conferencing add-ons use. As you upgrade your add-on, you must update your add-on's Apps Script project's manifest fields according to the tables below. You must update all relevant subproperties to the new addOns property.

Be sure to also update your manifest's oauthScopes field as needed to reflect the permissions your updated add-on requires.

To learn more about Google Workspace add-on manifests, see Manifests.

Gmail add-ons

Original manifest field	Action required
`gmail.composeTrigger`	Move to `addOns.gmail.composeTrigger`.
`gmail.contextualTriggers[]`	Move the list to `addOns.gmail.contextualTriggers[]`.
`gmail.logoUrl`	Move to `addOns.common.logoUrl`.
`gmail.name`	Move to `addOns.common.name`.
`gmail.openLinkUrlPrefixes[]`	Move the list to `addOns.common.openLinkUrlPrefixes[]`.
`gmail.primaryColor`	Move to `addOns.common.layoutProperties.primaryColor`.
`gmail.secondaryColor`	Move to `addOns.common.layoutProperties.secondaryColor`.
`gmail.universalActions[]`	Move the list to `addOns.common.universalActions[]`.
`gmail.universalActions[].text`	Move each `gmail.universalActions[].text` field to a corresponding `addOns.common.universalActions[].label` field.
`gmail.useLocalFromApp`	Move to `addOns.common.useLocaleFromApp`.

Calendar conferencing add-ons

Original manifest field	Action required
`calendar.createSettingsUrlFunction`	Move to `addOns.calendar.createSettingsUrlFunction`.
`calendar.conferenceSolution[]`	Move to `addOns.calendar.conferenceSolution[]`.
`calendar.logoUrl`	Move to `addOns.common.logoUrl`.
`calendar.name`	Move to `addOns.common.name`.

Step 4: Test your upgraded add-on

To test your upgraded add-on before publishing, see Testing Google Workspace add-ons.

Step 5: Request reviews of your upgraded add-on

All Google Workspace add-ons, whether an upgraded add-on or one built from scratch, must be approved before they can be listed in the Google Workspace Marketplace.

Follow these steps to submit your add-on for review:

Make sure your add-on fulfills all of the add-on publishing requirements.
Create a versioned deployment of your Google Workspace add-on (in the new Apps Script project) using the version of the code you want to publish. Don't attempt to publish using a head deployment.
If you added new scopes while upgrading your add-on, you must request OAuth verification. For example, if your Gmail add-on uses new Drive or Calendar scopes in the Google Workspace add-on version, you must submit those new scopes for verification. Verification often takes a few days to complete, so start the process as early as possible. Make sure your add-on is verified before proceeding to Step 6.

Step 6: Make your upgraded add-on available

Open the Google Workspace Marketplace SDK.
On the left, click Configuration. This panel contains a form where you provide information about your add-on.
Update the short description, detailed description, and screenshots of your listing to reflect the new functionality of the Google Workspace add-on.
Under Extensions, click the Upgrade to Google Workspace add-on button. In the textbox that appears, enter the new deployment ID you created for your Google Workspace add-on in the previous step. If your deployment ID is valid, a list of supported hosts appears.

Caution: Upgrading your add-on into a Google Workspace add-on this way is a one-time process that cannot be undone.
If you added new scopes to your Google Workspace add-on, make sure you add them to the OAuth 2.0 scopes section in the Configuration page. The scopes listed in that section should exactly match the scopes listed in your add-on's manifest.
Verify that the information you have entered in the form is correct. Then, click Save changes.

If you have questions or encounter an issue during this Google Workspace add-on upgrade process, contact us.

FAQ

The following are frequently-asked questions regarding add-on upgrades:

Can I upgrade my Editor add-on?

Most Editor add-ons can be moved over to Google Workspace add-ons. However, they can't be upgraded to Google Workspace add-ons as easily as add-ons for Gmail and Calendar.

If you want to migrate your Editor add-on to a Google Workspace add-on, you need to rewrite the add-on's UI from HTML to a Card-based interface, and update your JavaScript handling to the Card Service.

Some services in your existing Editor add-on might not be available in the Card Service. For example, if your Editor add-on includes a file picker, there isn't an equivalent available from the Card Service for Google Workspace add-ons.

Can I build a separate Google Workspace add-on and keep my existing add-on?

You're welcome to build additional Google Workspace add-ons under different brand names, but we don't permit separate Gmail or Calendar conferencing add-ons under the same brand name as your Google Workspace add-on. If you have questions or want to request an exception, contact us.

Will my users need to re-authorize the add-on after it's upgraded?

As long as your Google Workspace add-on uses the same underlying Cloud Platform (GCP) project, with an associated OAuth client ID, your users won't need to reauthorize permissions they've previously authorized for your original add-on. However, if you add new scopes during the upgrade process, your users must authorize those new scopes the first time they use the Google Workspace version of your add-on.

Can I upgrade my Chrome extension to a Google Workspace add-on and transfer users?

No. You can't transfer a Chrome extension's users, installs, and listing reviews. You must create a new Google Workspace add-on and direct users of your Chrome extension to the Google Workspace Marketplace.

Can I bundle multiple add-ons with my Google Workspace add-on?

See List app integrations together.