Synchronising functional accounts from Exchange (via PowerShell)

Introduction

This document explains how to synchronise functional accounts from Microsoft Exchange on-premise or Office 365 to ZIVVER using the ZIVVER SyncTool.

It is not recommended to create personal accounts in ZIVVER for email addresses that are used as shared mailbox. If an email address is shared, make it a functional account in ZIVVER.

If you want to use Single Sign On (SSO) for your organisation, make sure you’ve configured SSO before synchronising accounts with the SyncTool.

Currently, there are three ways to synchronise functional accounts to ZIVVER with the SyncTool:

  1. From Exchange on-premise or Office 365.
    Explained in this article.
  2. From Active Directory.
    Explained in Synchronising functional accounts from Active Directory.
  3. From an Excel file.
    Explained in Synchronising functional accounts from an Excel file..

This manual assumes installation of the SyncTool and configuration of the first two tabs is completed.

Technical requirements

The machine on which the SyncTool will be installed must meet the following technical requirements:

  • The machine has Microsoft .NET 4.7.2 or higher installed.
  • The machine has PowerShell modules installed to make a connection to Exchange on-premise or Office 365. To see which modules are installed open PowerShell and run the Get-Module -ListAvailable command.
  • The SyncTool can make a HTTPS connection (TLS v1.2) on the machine via port 443.
  • An Exchange account is available which has at least the following rights:
    • Distribution Groups.
    • View Only Configuration.
    • View Only Recipients.
  • The shared mailboxes to be synchronised has an email address and has delegates with email addresses or groups with FullAccess permission.

Using Exchange to synchronise accounts to ZIVVER

This section explains how to synchronise functional accounts to ZIVVER from Exchange on-premise or Office 365.

In this manual Exchange on-premise or Office 365 is the source for the synchronisation. The synchronisation is executed in one way: from the source to ZIVVER, not the other way around. You can determine which accounts are synchronised from the source to ZIVVER with filters.

Set up a connection to Exchange on-premise or Office 365

SyncTool tab | Step 3: Set up local users/group settings

In Source to use to sync users with ZIVVER select Exchange (via Powershell) from the dropdown menu.

Exchange type
Choose the Exchange type you want to use as a source to synchronise functional accounts to ZIVVER. Choose between:

  • Office 365
  • Exchange on-premise

Exchange address
Fill in the Exchange address. The SyncTool will use this address to set up a remote connection. The address will differ depending on the source you use.

  • Office 365
    Office 365 has a default address for remote PowerShell sessions, which will automatically be filled in: https://outlook.office365.com/powershell-liveid/.

  • Exchange on-premise
    The address should look like http://<ServerFQDN>/PowerShell/. Replace <ServerFQDN> with the fully qualified domain name of your Exchange server (for example, exchange01.example.com).

Use Kerberos
Do not use Kerberos when Exchange type is Office 365. The only way to connect remotely to Office 365 is via Basic Authentication.

Use Kerberos when Exchange type is Exchange on-premise. This is the default way to authenticate for Exchange on-premise.

Admin user Name
Fill in the username for the account that can be used to log into Exchange on-premise or Office 365. The account must meet the criteria in the technical requirements.

The username for Office 365 is always an email address. For Exchange on-premise the username often is preceded by the domain - for example company\name_exchange_account.

Password
Enter the password for the Office 365 or Exchange on-premise account.

OU to filter on
Optional: You can fill in the Exchange on-premise or Office 365 OU (not AD OU, unless it is this same) to filter on specific units. In most use cases an OU to filter on is not necessary. You can also filter on mailbox types in the next section.

Select shared mailbox types to include

SyncTool tab | Step 3: Set up local users/group settings

At the central column under Shared mailbox types to include you can select the shared mailbox types you want to include in your synchronisation. All shared mailbox types are selected by default.

  1. Review which shared mailbox types in your Exchange you want to include in the synchronisation.
    After this step you should know which shared mailbox types in Exchange you want a create functional account in ZIVVER for.
  2. Check the matching boxes for each shared mailbox type in the SyncTool.
    This will create a functional account for each shared mailbox type included.
  3. Uncheck the shared mailbox types you do not want to include in the synchronisation.
    This will prevent functional accounts from being created for unchecked shared mailbox types.
At least one shared mailbox type should be checked.

Assign ZIVVER OU (BETA)

Organizational Units (OUs) in ZIVVER is currently in BETA. All users are placed in the root OU / by default. If your organization not part of the BETA program from ZIVVER, all users should be placed in the root ou /. Follow the steps below, even if your organization is not part of the ZIVVER OU BETA program.

  1. Select Assign ZIVVER OU.
  2. Select Custom OU.
  3. Fill in / at OU UID.
    This places users in the root OU and prevent them from being marked as changed for every synchronization.

If your organization wants to use OU’s in ZIVVER, please contact ZIVVER Support.

How to check if your organization uses OU’s in ZIVVER

If your organization uses OU’s in ZIVVER, then you will see a tab called Organizational Units in your Organization settings. You can also try to visit the Organizational Units tab directly. If your organization does not use OU’s in ZIVVER, then you will see the following notification when clicking the link:

Sorry, the page you requested does not exist.

Filtering options

SyncTool tab | Step 3: Set up local users/group settings

These filtering options are optional. Currently you can only filter on the email address of shared mailboxes.

  1. Check Apply filter on users/groups.
  2. Enter the filter value(s) at Filter values.

    Use space, enter, semicolon or OR as OR-operator (i.e. match any of the list). Use AND with or without () to match all in the list.
  3. Choose between including or excluding results from your filter in the results.
    You can’t include and exclude in the same filter.

Read the next section Preview resources how to get the results based on your filtering options.

Preview resources

SyncTool tab | Step 3: Set up local users/group settings

If you click the button Preview resources, then the SyncTool will create a preview of what can be synchronised by connecting to your exchange and applying the previously configured filters on shared mailbox types and/or email addresses.

Previewing resources may take a couple of minutes or more since the SyncTool will run a PowerShell script in the background. If there are no error messages shown within one minute after clicking Preview resources, then let the SyncTool run untill it shows the results. To verify that the SyncTool process is still running, check that Windows Task Manager shows it is using CPU and memory.

If any error messages appear please read the message carefully to troubleshoot the message and close the SyncTool before retrying. Most common error messages are explained in Common error messages after previewing resources.

Synchronise users and groups

This section explains how to run the synchronisation after the SyncTool is configured.

SyncTool tab | Step 4: Synchronise users/groups

  1. Select the tab Step 4: Synchronise users/groups.
    A Get changes? pop-up will appear.
  2. Click YES.
    A Progress… pop-up will appear while the SyncTool loads the results from the source and compares the results to the current ZIVVER accounts.

    This process may take a couple of minutes or more since the SyncTool will run a PowerShell script in the background. If there are no error messages shown within one minute after clicking YES, then let the SyncTool run untill it shows the results. To verify that the SyncTool process is still running, check that Windows Task Manager shows it is using CPU and memory.
  3. Check the box [X] groups that are new or changed in local data to sync with ZIVVER under Functional/group account sync options.
    This will create new functional accounts and update information of functional accounts in future synchronisations.

    Do not check the box Groups that are missing in local data and should be removed from ZIVVER under Delete options for users and groups.

This could result in deletion of a functional account if a change is made to the source. All ZIVVER messages will be lost with the deletion of a functional account.

</div>

  1. Leave the other boxes unchecked.
    You are now ready to synchronise ZIVVER accounts.
  2. Click Run synchronisations.
    A Confirm actions pop-up appears with a summary of what is about to be synchronised.
  3. Click Yes.
    A Get changes pop-up will appear.
  4. Click Yes.
    A summary of the mutations will appear.
  5. Click OK.
    A Save As pop-up will appear. After saving the file the SyncTool will notify you if the export was successful.
  6. Click OK. The synchronisation is complete.

How to automate the SyncTool synchronisation using the Windows Task Scheduler

Common error messages after previewing resources

System.Exception: [outlook.office365.com] Connecting to remote server outlook.office365.com failed with the following error message: The WinRM-client received HTTP-statuscode403 from the external service WS-management.

Cause: The admin account entered at Step 3: Set up local users/group settings does not have permission to connect to Office 365 using remote PowerShell.

Solution: Give the administrator the permissions to do so, or enter different administrator credentials that have permission to connect to Exchange using remote PowerShell.

System.Exception: [outlook.office365.com] Connecting to remote server outlook.office365.com failed with the following error message: Access denied.

Cause: The entered credentials are incorrect. This could be either the username, password or both.

Solution: Enter the credentials again. The username for Office 365 is always an email address.

System.Management.Automation.Runspaces.PSSnapInException: Cannot load Windows PowerShell snap-in Microsoft.PowerShell.Diagnostics because of the following error: Could not load file or assembly ‘Microsoft.PowerShell.Commands’ or one of its dependencies. The system cannot find the file specified.

Cause: The machine running the SyncTool has a PowerShell version installed lower than version 3.

Solution: Update PowerShell to version 3 or higher. You can check which version is currently installed by opening PowerShell and running the $PSVersionTable.PSVersion. The column Major displays your current PowerShell version. If this command does not work, you are using PowerShell version 1.

Error UpdateAll 1: System.Net.Http.HttpRequestException: An error occurred while sending the request. —> System.Net.WebException: Unable to connect to the remote server.

Cause: The SyncTool is probably blocked by your Firewall.

Solution: Make sure the SyncTool can make a HTTPS connection (TLS v1.2) on the server via port 443 to https://*.zivver.com.

The WINRM client received an HTTP bad request status (400)

Cause: You are using https:// instead of http:// in the Exchange address.

Solution: Use the default connection URI for remote access to your Exchange on-premise server: http://<ServerFQDN>/PowerShell/ in combination with Kerberos authentication. Or try https://<ServerFQDN>/PowerShell/ without Kerberos authentication.

Still having trouble?

For the synchronisation to work, the SyncTool needs to set up a remote PowerShell session with your Exchange. If you are having trouble with connecting the SyncTool to your Exchange, please verify you can set up a connection using PowerShell instead of the SyncTool from the machine running the SyncTool. This might help you troubleshoot the problem. The Microsoft articles listed below show you the steps to set up a remote PowerShell session to your Exchange or Exchange online.

Common error messages after synchronising

Error processing {Name} ({Email address}) with status code ‘Forbidden’. You are not allowed to add this address to your organization. Does the account belong to a registered domain name?

Possible causes:.

  1. The account has an email address that does not belong to a claimed domain in ZIVVER.
    Claim a domain manual
  2. A ZIVVER account already exists for this email address, but it was created as a free account before your domain was claimed in ZIVVER.

Solution: The solution depends on whether or not you have claimed the domain in ZIVVER.

If have not claimed the domain in ZIVVER, go to domains and claim the domain. This allows the SyncTool to create a ZIVVER account for that domain.

If you have claimed the domain, visit the troubleshooting guide for functional accounts.

Was this article helpful?

thumb_up thumb_down