Applies to: On-premise Exchange Server (all versions), M365, Hybrid
Introduction
These instructions help administrators deploy Hoxhunt add-in to their organization in a granular way by changing the add-in availability and targeting it for specific user groups.
NOTE: These instructions mainly apply to on-premise Exchange environments, but can be used in hybrid environments (M365+on-premise Exchange) and M365 if needed.
- If you are running pure M365, we recommend to check Centralized Deployment option.
- If you are using on-premise Exchange only, we recommend reading further.
More about add-in deployment in on-premise Exchange: https://docs.microsoft.com/fi-fi/Exchange/manage-user-access-to-add-ins-exchange-2013-help
NOTE: Screenshots in this article are from O365 environment. There are some navigational and visual differences compared to on-premise Exchange Server's Exchange Admin Center (EAC).
IMPORTANT: Admin must have necessary permissions in order to install add-ins.
Please see this MS article: https://docs.microsoft.com/en-us/exchange/specify-who-can-install-and-manage-add-ins-exchange-2013-help
Deploy Hoxhunt add-in
2. Controlling add-in audience via Exchange PowerShell
1. Install Hoxhunt add-in
Step 1:
If you are configuring O365, log in to O365 and navigate to Admin > Admin Centers > Exchange.
If you are configuring on-premise Exchange, log in to Exchange Admin Center.
Step 2. Under organization section, select add-ins (or apps if configuring on-premise Exchange).
Step 3. Click the "+ icon" and select Add from URL.
Step 4. Enter "https://officejs.hoxhunt.com/api/v1/manifest/default/manifest.xml"
and select install.
NOTE: If you have been provided with a different URL, please use that one instead.
Step 5. Check the “Make this add-in available to users in your organization”, select “Optional, disabled by default”, and click Save.
If you encounter any issues with "Add from URL..." command, please check Troubleshooting section at the end of this article.
If you wish to distribute Hoxhunt add-in to all your entire organization (tenant), please select "Optional, enabled by default" or "Mandatory, always enabled. Users can't disable this add-in."
2. Controlling add-in audience via Exchange PowerShell
Distributing add-ins to selected audience in Outlook differ from distributing other Office add-ins. Add-in visibility to specific user group can be done via Exchange (Online) PowerShell.
IMPORTANT:
- You must re-run the PowerShell commands every time users are added or removed from the distribution group.
- Distribution groups used for add-in distribution can only hold up to 1,000 users. If you have more users in the distribution group, the distribution will fail.
- You may need to disable your admin account's two-factor authentication to be able to connect to Exchange Online via Powershell. Remember to turn it back on when you're done!
2.1 Open connection to Exchange PowerShell
1. Open PowerShell with administrator rights.
2. Enable PowerShell to run signed scripts by running the following command:
Set-ExecutionPolicy RemoteSigned
3. Enter admin account username and password by running the following command:
$UserCredential = Get-Credential
4a. Configure a connection to Exchange Online:
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Authentication Basic -Credential $UserCredential
--OR--
4b. Configure a connection to your on-premise Exchange:
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://<ServerFQDN>/PowerShell/ -Authentication Basic -Credential $UserCredential
For more information please check this Microsoft KB article.
5. Open the connection to Exchange (Online) PowerShell:
Import-PSSession $Session -DisableNameChecking
6. You should be connected now. You can test it by running a command Get-Mailbox to test the connection.
7. Once you are done, close your Exchange Powershell session:
Remove-PSSession $session
8. Proceed to step 2.2. below to distribute the add-in.
2.2 Option A: Distribute add-in to a handful of users:
7a. Create a distribution group that includes the users you'd like to distribute the add-in to. You can name it anyway you like but in this example we use the name HoxHunt_UserGroup.
After the -Members flag enter a comma separated list of the users email addresses. Change the parameters and run the New-DistributionGroup command:
New-DistributionGroup -Name "HoxHunt_UserGroup" -Members billy.bluff@hoxhunt.com,clive.conman@hoxhunt.com,jane.joker@hoxhunt.com
8a. Save the users of the distribution group in a variable, run command where you use the same name for the distribution group you did in the previous step, in the example it is HoxHunt_UserGroup:
$users= Get-DistributionGroupMember HoxHunt_UserGroup
9a. Enable Hoxhunt add-in for users in your Distribution group:
Set-App -OrganizationApp -Identity 41f6a6f2-f271-4d8a-8508-26ded39437af -ProvidedTo SpecificUsers -UserList $users.Identity -DefaultStateForUser Enabled
The add-in should become visible for the users in a few minutes but some cases it may take up to 24 hours.
10a. Close your Exchange Powershell session:
Remove-PSSession $session
REMEMBER: You need to re-run Set-App command every time you add users to your distribution group in the future.
2.2 Option B: Distribute add-in to an Active Directory group:
NOTE: You must have ActiveDirectory module (addsadministration) installed in order to proceed with this option. Please use import-module ActiveDirectory or check this article for more information.
7b. Create an AD group in Active Directory Users and Groups.
8b. Link users in the AD group to $users variable:
$users = get-adgroupmember "ENTER-GROUP-NAME" | %{(Get-AdUser $_.samaccountname -Properties userprincipalname).userprincipalname}
You can check the users were picked successfully by running the following command:
$users
9b. Enable Hoxhunt add-in for users in your AD group:
Set-App -OrganizationApp -Identity 41f6a6f2-f271-4d8a-8508-26ded39437af -ProvidedTo SpecificUsers -UserList $users -DefaultStateForUser Enabled
10b. Check that Hoxhunt add-in was set correctly:
Get-App -OrganizationApp -Identity "41f6a6f2-f271-4d8a-8508-26ded39437af" | Format-List DisplayName,AppId,Enabled,Default*,ProvidedTo,UserList
The add-in should become visible for the users in a few minutes but some cases it may take up to 24 hours.
Troubleshooting
Problem | Explanation |
When installing add-in via URL:
error Value cannot be null. Parameter name: constraintProvider
|
This error means your Exchange server doesn't have access to the manifest URL location. Workaround: 1. Copy-paste manifest URL to a web browser. XML-formatted result should appear. If it doesn't, please use a browser whose traffic is not restricted. 2. Save the contents by selecting File > Save As... and name the file as manifest.xml 3. Go back to Section 1 Step 3 and select "Add from file..." |
When installing add-in via Exchange Admin Center > organization > apps:
error |
This error means your Exchange server doesn't have access to the manifest URL location. Workaround: 1. Copy-paste manifest URL to a web browser. XML-formatted result should appear. If it doesn't, please use a browser whose traffic is not restricted. 2. Save the contents by selecting File > Save As... and name the file as manifest.xml 3. Go back to Section 1 Step 3 and select "Add from file..." |
When running Set-App cmdlet: Too many recipients specified, the limit is 1000 recipients |
Set-App command can be used only for up to 1,000 users. This is a limitation from Microsoft. Workaround #1: Consider distributing Hoxhunt add-in to all users (Everyone) in the tenant. Workaround #2: Deploy multiple instances of Hoxhunt add-in and assign up to 1,000 users to each add-in. Please contact Hoxhunt Support to receive the "alternative" manifests.
|
When installing add-in via URL: The operation couldn't be performed because object '\xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' couldn't be found on 'Microsoft.Exchange.Management.Extension.OWAAppDataProviderForNonMailboxUser'. |
UNVERIFIED |
Hoxhunt add-in is not visible to new users after adding them to the distribution group or AD group. |
Step #1: Make sure you re-run the PowerShell commands. Step #2: Check that the distribution has gone through with the following PowerShell command: Get-App -OrganizationApp -Identity "41f6a6f2-f271-4d8a-8508-26ded39437af" | Format-List DisplayName,AppId,Enabled,Default*,ProvidedTo,UserList Note: -Identity value may be different if your organization has a customized Hoxhunt button. Step #3: Remove the add-in and re-do the distribution steps from beginning. |
get-adgroupmember command doesn't recognize my AD group. It throws the following error: get-adgroupmember : Cannot find an object with identity: 'YOUR_GROUP_NAME' under: 'DC=ad,DC=xxxxxxxx,DC=fi'. At line:1 char:10 |
If you created the AD group through EAC, you need to use the pre-Windows 2000 group name available in Active Directory Users and Groups. |
Reference:
- Connect to Exchange Online PowerShell: https://technet.microsoft.com/en-us/library/jj984289(v=exchg.160).aspx
- Set-App command reference: https://technet.microsoft.com/en-us/library/jj218630(v=exchg.160).aspx
- Connecting to on-premise Exchange via PowerShell: https://docs.microsoft.com/en-us/powershell/exchange/exchange-server/connect-to-exchange-servers-using-remote-powershell?view=exchange-ps