Use the Centralized Deployment PowerShell cmdlets to manage add-ins

As a Microsoft 365 global, or Exchange admin, you can deploy Office add-ins to users via the Centralized Deployment feature (see Deploy Office Add-ins in the admin center). In addition to deploying Office add-ins via the Microsoft 365 admin center, you can also use Microsoft PowerShell. Install the O365 Centralized Add-In Deployment Module for Windows PowerShell.

After you download the module, open a regular Windows PowerShell window and run the following cmdlet:

 Import-Module -Name O365CentralizedAddInDeployment

Connect using your admin credentials

Before you can use the Centralized Deployment cmdlets, you need to sign in.

  1. Start PowerShell.

  2. Connect to PowerShell by using your company admin credentials. Run the following cmdlet.

Connect-OrganizationAddInService
  1. In the Enter Credentials page, enter your Office 365 global admin credentials. Alternately, you can enter your credentials directly into the cmdlet.

    Run the following cmdlet specifying your company admin credentials as a PSCredential object.

$secpasswd = ConvertTo-SecureString "MyPassword" -AsPlainText -Force
$mycredentials = New-Object System.Management.Automation.PSCredential ("serviceaccount@contoso.com", $secpasswd)
Connect-OrganizationAddInService -Credential $mycredentials

Note

For more information about using PowerShell, see Connect to Office 365 PowerShell.

Upload an add-in manifest

Run the New-OrganizationAdd-In cmdlet to upload an add-in manifest from a path, which can be either a file location or URL. The following example shows a file location for the value of the ManifestPath parameter.

New-OrganizationAddIn -ManifestPath 'C:\Users\Me\Desktop\taskpane.xml' -Locale 'en-US'

You can also run the New-OrganizationAdd-In cmdlet to upload an add-in and assign it to users or groups directly by using the Members parameter, as shown in the following example. Separate the email addresses of members with a comma.

New-OrganizationAddIn -ManifestPath 'C:\Users\Me\Desktop\taskpane.xml' -Locale 'en-US' -Members  'KathyBonner@contoso.com', 'MaxHargrave@contoso.com'

Upload an add-in from the Office Store

Run the New-OrganizationAddIn cmdlet to upload a manifest from the Office Store.

In the following example, the New-OrganizationAddIn cmdlet specifies the AssetId for an add-in for a United States location and content market.

New-OrganizationAddIn -AssetId 'WA104099688' -Locale 'en-US' -ContentMarket 'en-US'

To determine the value for the AssetId parameter, you can copy it from the URL of the Office Store webpage for the add-in. AssetIds always begin with "WA" followed by a number. For example, in the previous example, the source for the AssetId value of WA104099688 is the Office Store webpage URL for the add-in: https://store.office.com/en-001/app.aspx?assetid=WA104099688.

The values for the Locale parameter and the ContentMarket parameter are identical and indicate the country/region you're trying to install the add-in from. The format is en-US, fr-FR. and so forth.

Note

Add-ins uploaded from the Office Store will update automatically within a few days of the latest update being available on the Office Store.

Get details of an add-in

Run the Get-OrganizationAddIn cmdlet as shown below to get details of all add-ins uploaded to the tenant, included an add-in's product ID.

Get-OrganizationAddIn

Run the Get-OrganizationAddIn cmdlet with a value for the ProductId parameter to specify which add-in you want to retrieve details for.

Get-OrganizationAddIn -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122

To get full details of all the add-ins plus the assigned users and groups, pipe the output of the Get-OrganizationAddIn cmdlet to the Format-List cmdlet, as shown in the following example.

Get-OrganizationAddIn |Format-List

Turn on or turn off an add-in

To turn off an add-in so users and groups that are assigned to it will no longer have access, run the Set-OrganizationAddIn cmdlet with the ProductId parameter and the Enabled parameter set to $false, as shown in the following example.

Set-OrganizationAddIn -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -Enabled $false

To turn an add-in back on, run the same cmdlet with the Enabled parameter set to $true.

Set-OrganizationAddIn -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -Enabled $true

Add or remove users from an add-in

To add users and groups to a specific add-in, run the Set-OrganizationAddInAssignments cmdlet with the ProductId, Add, and Members parameters. Separate the email addresses of members with a comma.

Set-OrganizationAddInAssignments -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -Add -Members 'KathyBonner@contoso.com','sales@contoso.com'

To remove users and groups, run the same cmdlet using the Remove parameter.

Set-OrganizationAddInAssignments -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -Remove -Members 'KathyBonner@contoso.com','sales@contoso.com'

To assign an add-in to all users on the tenant, run the same cmdlet using the AssignToEveryone parameter with the value set to $true.

Set-OrganizationAddInAssignments -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -AssignToEveryone $true

To not assign an add-in to everyone and revert to the previously assigned users and groups, you can run the same cmdlet and turn off the AssignToEveryone parameter by setting its value to $false.

Set-OrganizationAddInAssignments -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -AssignToEveryone $false

Update an add-in

To update an add-in from a manifest, run the Set-OrganizationAddIn cmdlet with the ProductId, ManifestPath, and Locale parameters, as shown in the following example.

Set-OrganizationAddIn -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122 -ManifestPath 'C:\Users\Me\Desktop\taskpane.xml' -Locale 'en-US'

Note

Add-ins uploaded from the Office Store will update automatically within a few days of the latest update being available on the Office Store.

Delete an add-in

To delete an add-in, run the Remove-OrganizationAddIn cmdlet with the ProductId parameter, as shown in the following example.

Remove-OrganizationAddIn -ProductId 6a75788e-1c6b-4e9b-b5db-5975a2072122

Customize Microsoft Store add-ins for your organization

You must customize the add-in before you deploy it to your organization. Add-ins older than version 1.1 are not supported by this feature.

We recommend that you deploy a customized add-in to yourself first to make sure it works as expected before you deploy it to your entire organization.

Note also the following restrictions:

  • All URLs must be absolute (include http or https) and valid.

  • DisplayName must not exceed 125 characters

  • DisplayName, Resources and AppDomains must not include the following characters:

    • <
    • >
    • ;
    • =

If you want to customize an add-in that has been deployed, you have to uninstall it in the admin center, and see remove an add-in from local cache for steps to remove it from each computer it has been deployed to.

To customize an add-in, run the Set –OrganizationAddInOverrides cmdlet with the ProductId as a parameter, followed by the tag you want to overwrite and the new value. To find out how to get the ProductId see get details of an add-in in this article. For example:

 Set-OrganizationAddInOverrides -ProductId 5b31b349-2c41-4f94-b720-6ee40349d391 -IconUrl "http://site.com/img.jpg" 

To customize multiple tags for an add-in, add those tags to the commandline:

Set-OrganizationAddInOverrides -ProductId 5b31b349-2c41-4f94-b720-6ee40349d391 -Hosts h1, 2 -DisplayName "New DocuSign W" -IconUrl "http://site.com/img.jpg" 

Important

You must apply multiple customized tags to one add-in as one command. If you customize tags one by one, only the last customization will be applied. Additionally, if you customize a tag by mistake, you must remove all customizations and start over.

Tags you can customize

Tag Description
<IconURL>
The URL of the image used as the add-in’s icon (in admin center).
<DisplayName> The title of the add-in (in admin center).
<Hosts> List of apps that will support the add-in.
<SourceLocation> The source URL that the add-in will connect to.
<AppDomains> A list of domains that the add-in can connect with.
<SupportURL> The URL users can use to access help and support.
<Resources> This tag contains a number of elements including titles, tooltips, and icons of different sizes.

Customize Resources tag

Any element in the tag of the manifest can be customized dynamically. You first need to check the manifest to find the element id to which you want to assign a new value. The tag looks like this:

<Resources>  
    <bt:Images> 
          <bt:Image id=”img16icon” DefaultValue=”http://site.com/img.jpg” 
    </bt:Images> 
</Resources> 

In this case, the element id for the image is “img16icon” and the value associated with it is “http://site.com/img.jpg.”

Once you have identified the elements you want to customize, use the following command in Powershell to assign new values to the elements:

Set-OrganizationAddInOverrides -Resources @{“ElementID” = “New Value”; “NextElementID” = “Next New Value”} 

You can customize as many elements with the command as you need to.

Remove customization from an add-in

The only option currently available for deleting customizations is to delete all of them at once:

Remove-OrganizationAddInOverrides -ProductId 5b31b349-2c41-4f94-b720-6ee40349d391 

View add-in customizations

To view a list of applied customizations, run the Get-OrganizationAddInOverrides cmdlet. If Get-OrganizationAddInOverrides is run without a ProductId then a list of all add-ins with applied overrides are returned.

Get-OrganizationAddInOverrides 

If ProductId is specified, then a list of overrides applied to that add-in is returned.

Get-OrganizationAddInOverrides -ProductId 5b31b349-2c41-4f94-b720-6ee40349d391 

Remove an add-in from local cache

If an add-in has been deployed, it has to be removed from the cache in each computer before it can be customized. To remive an add-in from cache:

  1. Navigate to the “Users” folder in C:\
  2. Go to your user folder
  3. Navigate to AppData\Local\Microsoft\Office and select the folder associated with your version of Office
  4. In the Wef folder delete the Manifests folder.

Get detailed help for each cmdlet

You can look at detailed help for each cmdlet by using the Get-help cmdlet. For example, the following cmdlet provides detailed information about the Remove-OrganizationAddIn cmdlet.

Get-help Remove-OrganizationAddIn -Full