Edit

Convert an add-in to use the unified manifest for Microsoft 365

To upgrade an add-in that uses the add-in only manifest to a full App for Microsoft 365 to which you can add Teams capabilities or a Copilot extension, you need to convert it to use the unified manifest for Microsoft 365.

There are four basic tasks to converting an add-in project from the add-in only manifest to the unified manifest.

  • Ensure that your manifest is ready to convert.
  • Convert the XML-formatted add-in only manifest itself to the JSON format of the unified manifest.
  • Edit the newly created unified manifest.
  • Package the new manifest and two icon image files (described later) into an app package (zip) file for sideloading or deployment. Depending on how you sideload the converted add-in, this task may be done for you automatically.

Note

For information on clients and platforms that support Office Add-ins that use the unified manifest for Microsoft 365, see Office Add-ins with the unified app manifest for Microsoft 365.

Note

Ensure that your manifest is ready to convert

The following sections describe conditions that must be met before you convert the manifest.

Uninstall the existing version of the add-in

To avoid conflicts with UI control names and other problems, be sure the existing add-in isn't installed on the computer where you do the conversion. If you experience any difficulties uninstalling the add-in, see Remove a ghost add-in.

Ensure that you have two special image files

If your add-in only manifest doesn't already have both <IconUrl> and <HighResolutionIconUrl> (in that order) elements, then add them just below the <Description> element. The values of the DefaultValue attribute should be the full URLs of image files. The images must be a specified size as shown in the following table.

Office application <IconUrl> <HighResolutionIconUrl>
Outlook 64x64 pixels 128x128 pixels
All other Office
applications		 32x32 pixels 64x64 pixels

The following markup is an example.

<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MailApp">
  <Id>01234567-89ab-cdef-0123-4567-89abcdef0123</Id>
  <Version>1.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-us</DefaultLocale>
  <DisplayName DefaultValue="Great Add-in"/>
  <Description DefaultValue="A great add-in."/>
  <IconUrl DefaultValue="https://localhost:3000/assets/icon-64.png" />
  <HighResolutionIconUrl DefaultValue="https://localhost:300/assets/icon-128.png" />

  <!-- Other markup omitted -->

Reduce the number of add-in commands as needed

An add-in that uses the unified manifest may not have more than 20 add-in commands. If the total number of <Action> elements in the add-in only manifest is greater than 20, you must redesign the add-in to have no more than 20.

Update the add-in ID, version, domain, and function names in the manifest

  1. Change the value of the <ID> element to a new random GUID.

  2. Update the value of the <Version> element and ensure that it conforms to the semver standard (MAJOR.MINOR.PATCH). Each segment can have no more than five digits. For example, change the value 1.0.0.0 to 1.0.1. The semver standard's prerelease and metadata version string extensions aren't supported.

  3. Be sure that the domain segment of the add-in's URLs in the manifest are pointing to https://localhost:3000.

  4. If your manifest has any <FunctionName> elements, make sure their values have fewer than 65 characters.

    Important

    The value of this element must exactly match the name of an action that's mapped to a function in a JavaScript or TypeScript file with the Office.actions.associate function. If you change it in the manifest, be sure to change it in the actionId parameter passed to associate() too.

Shorten string values as needed

Review and change, as needed, manifest values in light of the following effects of the conversion.

  • The first 30 characters of <DisplayName> becomes the value of "name.short" in the unified manifest.
  • The first 100 characters of <DisplayName> becomes the value of "name.full" in the unified manifest.
  • The first 250 characters of <Description> becomes the value of "description.short" in the unified manifest.
  • The first 4000 characters of <Description> becomes the value of "description.full" in the unified manifest.
  • The first 32 characters of the <ProviderName> becomes the value of "developer.name" in the unified manifest.

Note

If any of these elements have child <Override> elements, be sure to adjust the localized strings as needed.

Ensure conformity of custom functions configuration

If your add-in has custom functions, then it includes a JSON configuration file. Some requirements for this file weren't always enforced by Office or Microsoft Marketplace in the past, but they are all enforced when the add-in has a unified manifest. Before you convert the manifest, ensure that this JSON file conforms to all requirements. For more information, see Custom functions naming and localization and Manually create JSON metadata for custom functions.

In particular, note that all function names and function ids must have at least 3 characters and that each function object must have a "result" property.

Verify that the modified add-in only manifest works

  1. Validate the modified add-in only manifest. See Validate an Office Add-in's manifest.

  2. Verify that the add-in can be sideloaded and run. See Sideload an Office Add-in for testing.

Resolve any problems before you attempt to convert the project.

Conversion tools and options

There are several ways to carry out the remaining tasks, depending on the IDE and other tools you want to use for your project, and on the tool you used to create the project.

Note

Conversion of the manifest is one of the effects of importing the add-in project into Agents Toolkit if you do so using the toolkit's importation feature. For details, see Import an add-in project to Agents Toolkit.

Convert projects created with the Yeoman generator for Office Add-ins (aka "Yo Office")

If the project was created with the Yeoman generator for Office Add-ins, convert it using the following steps.

  1. In the root of the project, open a command prompt or bash shell and run the following command. This converts the manifest and updates the package.json to specify current tooling packages. The new unified manifest is in the root of the project and the old add-in only manifest is in a backup.zip file. For details about this command, see Office-Addin-Project.

    npx office-addin-project convert -m <relative-path-to-XML-manifest>

  2. Carry out the steps in Edit the new unified manifest.

Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office)

If your project wasn't created with Yo Office, use the office-addin-manifest-converter tool.

  1. In the root of the project, open a command prompt or bash shell and run the following command. This command puts the unified manifest in a subfolder with the same name as the filename stem of the original add-in only manifest. For example, if the manifest is named MyManifest.xml, the unified manifest is created at .\MyManifest\MyManifest.json. For more details about this command, see Office-Addin-Manifest-Converter.

    npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>

  2. Carry out the steps in Edit the new unified manifest.

Edit the new unified manifest

  1. Open the unified manifest file.

  2. Update the "$schema" and "manifestVersion" properties at the top of the file to use either the latest released version or the preview version. The following are examples:

    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.30/MicrosoftTeams.schema.json#",
"manifestVersion": "1.30",

    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json#",
"manifestVersion": "devPreview",

    Note

    Treat these two property values as case-sensitive.

  3. Navigate to the "developer" property and ensure there are child "privacyUrl" and "termsOfUseUrl" properties. These properties must have appropriate values with a localhost domain.

  4. You can now sideload the add-in.

Special considerations when converting an add-in with custom functions

Currently, neither of the tools described in the Conversion tools and options section add the needed custom function support to the unified manifest. You must manually add a "extensions.runtimes.customFunctions" property and map the runtime, namespace, metadata URL, and code URLs from the add-in only manifest. The exact runtime configuration depends on whether the existing add-in uses a JavaScript-only runtime or a shared runtime.

For a complete walkthrough, including XML-to-JSON examples, validation, and testing, see Convert custom functions to the unified manifest.

Some combinations of Office versions and platforms don't yet support the unified manifest. See Unified manifest - Client and platform support. Currently, to keep your custom functions available on these Office versions, you must maintain both your existing add-in with the add-in only manifest and your new add-in. Include the optional metadataUrl property in the "customFunctions" object and give it the same value that's used in the resource string referenced by the Metadata element of the add-in only manifest. Also keep the metadata file in the unified manifest version of the add-in.

Special considerations when converting an add-in with event-based activation

Currently, neither of the tools described in the Conversion tools and options section add the needed event-based activation support to the unified manifest. We're working hard to update the tools. In the meantime, you must manually add some JSON to the manifest. Specifically, you must add an "autoRunEvents" object as a direct child of the "extensions" property, and populate it with data copied from the add-in only manifest. The following is an example. Note the following about this code.

  • For each <LaunchEvent> element in the add-in only manifest, there's an object in the "events" array.
  • The "type" property of each event object gets the value that's in the Type attribute of the <LaunchEvent> element. But the naming convention is different in the unified manifest. See the tables at Supported events to find the unified manifest name that maps to the name in your add-in only manifest.
  • The "actionId" property of each event object gets the value that's in the FunctionName attribute of the <LaunchEvent> element.
"autoRunEvents": [
   {
      "events": [
         {
            "type": "newMessageComposeCreated",
            "actionId": "onNewMessageComposeHandler"
         },
         {
            "type": "newAppointmentOrganizerCreated",
            "actionId": "onNewAppointmentComposeHandler"
         }
      ]
   }
]

If there's a SendMode attribute in the <LaunchEvent>, the event object should have an "options" property with a "sendMode" child property that has the same value as the attribute, except that the property's value should begin with a lower case letter. So, if SoftBlock is the value in the add-in only manifest, then "softBlock" should be used in the unified manifest. If there's a HeaderName attribute in the <LaunchEvent>, the event object should have an "options" property with a "headerName" child property that has the same value as the attribute. The following is an example.

"autoRunEvents": [
   {
      "events": [
         {
            "type": "newMessageComposeCreated",
            "actionId": "onNewMessageComposeHandler",
            "options": {
               "sendMode": "softBlock",
               "headerName": "contoso-encrypted"
            }
         },
          ...
      ]
   }
]

If the ancestor <VersionOverrides> element of the <LaunchEvent> element has a <Requirements> element, then you should add a "requirements" property to the autorun event object. The following is an example. Note the following about this code.

  • The value of the "capabilities.name" property comes from the Name attribute of the <Requirements><Sets><Set> element.
  • The value of the "capabilities.minVersion" come from the MinVersion attribute, if there is one, of the <Requirements><Sets><Set> element. Otherwise, it comes from the DefaultMinVersion attribute of the parent <Requirements><Sets> element.
"autoRunEvents": [
   {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.10"
              }
          ]
      },
      "events": [ ...  ]
   }
]

Sideload the add-in

The sideloading process depends on how the project was created.

Sideload an add-in that was created with the Yeoman generator for Office Add-ins

  1. Run npm install.
  2. To sideload the add-in, see Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office). The app package zip file is created for you as part of this process.

Sideload NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins

Once you have the unified manifest created, there are two ways to create the zip file and sideload it. For more information, see Sideload other NodeJS and npm projects.

Note

If the original add-in only manifest used any <Override> elements to localize strings in the manifest, then the conversion process produces JSON string files for each localized language. These files must also be included in the app package zip file, and they must be at the relative path indicated in the "localizationInfo.additionalLanguages.file" property.

Next steps

Consider whether to maintain both the old and new versions of the add-in. See Manage both a unified manifest and an add-in only manifest version of your Office Add-in.

  • Last updated on