Introduction

This document explains how you synchronise personal accounts and functional accounts from an Excel file to Zivver using the Zivver SyncTool. You can use synchronisation via an Excel file when you can not use Active Directory on-premise for synchronising personal accounts.

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.

Personal AD accounts can be synchronised to Zivver with the SyncTool in one of two ways:

1. From an Excel file
   Explained in this article.
2. From Active Directory
   Explained in Synchronising personal accounts from Active Directory.

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 SyncTool can make a HTTPS connection (TLS v1.2) on the machine via port 443.
• A service account (SA) is available which that meets the following requirements:
  • Can be used to run a basic task in the Windows Task Scheduler.

Using an Excel file to synchronise accounts to Zivver

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

This article describes two ways to synchronise personal accounts. Which section is relevant depends on whether or not your organisation is using Single Sign-On (SSO).

If you want to synchronise functional accounts, follow the instructions at the end of the sections listed below. Go directly to functional accounts if you do not whish to synchronise personal accounts using an Excel file.

• In this article, go to Personal accounts when using SSO, if you have chosen Users log in via SSO at User login method.
• In this article, go to Personal accounts without using SSO, if you have chosen Users need to log into Zivver with a password at User login method.

Personal accounts when using SSO

This section explains how to synchronise personal accounts to Zivver from an Excel file (.xlsx) using the SyncTool.

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

1. In Source to use to sync users with Zivver select Excel file (xlsx) or Comma or Tab Seperated file (csv) from the dropdown menu.
2. Download the Excel file template by clicking Download template Excel File by clicking here.
   You will be asked to save an .xslx file named Zivver Users import template.

In the Excel file there are eight columns (E-mail; Full name; ZivverAccountKey; Mobile phone; Is Active; Delegates; Aliases; OU UID) in the first tab User Accounts. Use one row for each user account and fill in the properties for each column, please note not all properties are mandatory. Down below is a description of what each column means, which syntax is expected and an example.

E-mail

• Example syntax: john.doe@example.com

This field is mandatory. Zivver accounts must have an email address as username. You can not enter email aliases or delegations through this method, only enter the primary email address. Email aliases and delegations are added through another column discussed below.

Full name

• Example syntax: John Doe

This field is mandatory. It contains the name of a user. This name will be displayed in a Zivver notification message, therefore you should enter the name in a way that matches how your organisation displays names to external recipients in normal emails. This could be for example the first letter and last name (J. Doe) or the full name (John Doe).

ZivverAcountKey

• Example syntax: N/A

This field is mandatory. The ZivverAccountKey is used to encrypt the password of the user login in. When using SSO the value for ZivverAccountKey should match the value of the Identity Provider (IdP) secret that is used in the SSO configuration.

For example: If Azure AD is your IdP and you have configured user.objectid in the SSO setup in Azure AD as ZivverAccountKey, then make sure the value of user.objectid is filled into the Excel sheet for every user in the ZivverAccountKey column. This ensures accounts use the same value for the ZivverAccountKey when being created as they do when logging in via your IdP.

If the ZivverAccountKey configured at your IdP is different from the ZivverAccountKey used to create accounts, users can not log in. In such cases, Zivver will display the following message:

Password required

For “name@example.com”

Please enter your password in order to start using Zivver. You will only have to do this once.

If you encounter this problem read the Azure SSO troubleshooting guide for a solution.

Mobile phone

• Example syntax: +44 1234 567890 or 0044 1234 567890

Mobile phone numbers are used to automatically configure 2FA via SMS for users that have a valid entry in the mobile phone column. Nothing happens if the field is blank. Landline numbers should be avoided, because landline numbers often cannot receive SMS codes. This means the user cannot log in when Zivver asks for a second factor. Mobile numbers should contain the country code as shown in the example above.

Is Active

• Example syntax: 1 or 0 or TRUE or FALSE or yes or no

This field is mandatory. The value in IsActive determines whether a Zivver account is created, suspended or deleted. If an user is active, has an email addres, name and ZivverAccountKey, a Zivver account will be created if there is no current account for that email address. Suspended AD users can get suspended or deleted it Zivver, depending on the synchronisation options. Choose which boolean you want to use and for every user fill in either 1 or 0, TRUE or FALSE, yes or no. It is not possible to create a new user with a false IsActive state.

Delegates

• Example syntax: john.doe@example.com;jane.doe@example.com

Delegates get full access to the Zivver inbox of a personal account. The filled in email addresses must have an active Zivver account in your Zivver organization, and the domain of the email addresses must be claimed in Zivver. If the delegate does not have an active Zivver account, is not a member of your Zivver organization or has an email address under a domain that your Zivver organization has not claimed in Zivver, then the Delegates property will be ignored.

Aliases

• Example syntax: alias@example.com;secondalias@example.com

If a Zivver message is sent to an alias, then the Zivver message is delivered in the inbox of the primairy email address. The filled in email addresses in the Aliases column must be claimed in Zivver. If the filled in email addresses at Aliases has received a Zivver message before creating the alias via the Zivver SyncTool, then the alias property will be ignored. In such cases, you should merge accounts before the next synchronisation.

Smtp-addresses that are not claimed in Zivver should be excluded from synchronisation to Zivver in the Zivver synctool. If you want to synchronise email aliases to Zivver for unclaimed domains, you should first claim the domain in Zivver.

OU UID

• Example syntax: / or

This is a mandatory field. Fill in / if your organization does not use Organizational Units in Zivver. The forward slash / puts users in the Root OU. Users reside in the root OU when your organization does not use Organizational Units in Zivver. If your organization does use Organizational Units in Zivver, then fill in a OU UID for each user. The value filled in in this column determines in which Organizational Units a user will be placed. A user can only be in one Organizational Unit at the time.

Example and further steps

The table below shows a filled in example. Note how an example user.objectid is used for the ZivverAccountKey.

E-mail	Full name	ZivverAccountKey	Mobile phone	Is active	Delegates	Aliases	OU UID
john.doe@example.com	John Doe	b836ddga-24v0-15h6-hg9a-8473g523658e	+44 1234 567890	1	jane.doe@example.com	john.d@example.com	/
jane.doe@example.com	Jane Doe	c636hzga-54g0-18h8-dg2c-5273d578658i	0044 7890 123456	0		jane.d@example.com	/

After completing the Excel file, you can add functional accounts in the same file or continue and synchronise only personal accounts. Adding functional accounts to the same Excel file lets you synchronise both personal accounts and functional accounts with just one SyncTool profile.

• Add functional accounts to the Excel file.
• Do not add functional accounts and synchronise only personal accounts.

Personal accounts without using SSO

This section explains how to synchronise personal accounts to Zivver from an Excel file (.xlsx) using the SyncTool.

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

1. In Source to use to sync users with Zivver select Excel file (xlsx) or Comma or Tab Seperated file (csv) from the dropdown menu.
2. Download the Excel file template by clicking Download template Excel File by clicking here.
   You will be asked to save an .xslx file named Zivver Users import template.

In the Excel file there are eight columns (E-mail; Full name; Temporary password; Mobile phone; Is Active; Delegates; Aliases; OU UID) in the first tab User Accounts. Use one row for each user account and fill in the properties for each column, please note not all properties are mandatory. Down below is a description of what each column means, which syntax is expected and an example.

E-mail

• Example syntax: john.doe@example.com

This field is mandatory. Zivver accounts must have an email address as username. You can not enter email aliases or delegations through this method, only enter the primary email address. Enter aliases manually.

Full name

• Example syntax: John Doe

This field is mandatory and contains the name of a user. This name will be displayed in a Zivver notification message, therefore you should enter the name in a way that matches how your organisation displays names to external recipients in normal emails. This could be for example the first letter and last name (J. Doe) or the full name (John Doe).

Temporary password

• Example syntax: N/A

If you synchronize accounts from an Excel file without using SSO, you create accounts with a temporary password. Then, users must enter a temporary password at the first login attempt and create their own password. Zivver will display the following message.

Password required

For “name@example.com”

Please enter your password in order to start using Zivver. You will only have to do this once.

The temporary password column should contain the temporary password. You can either enter a value for each user or leave it blank. If you leave the temporary password column blank, the SyncTool will randomly generate a password and prompt to save a file after synchronisation, with the generated passwords.

Mobile phone

• Example syntax: +44 1234 567890 or 0044 1234 567890

Mobile phone numbers are used to automatically configure 2FA via SMS for users that have a valid entry in the mobile phone column. Nothing happens if the field is blank. Landline numbers should be avoided, because landline numbers often cannot receive SMS codes. This means the user cannot log in when Zivver asks for a second factor. Mobile numbers should contain the country code as shown in the example above.

Is active

• Example syntax: 1 or 0 or TRUE or FALSE or yes or no

This field is mandatory. The value in IsActive determines whether a Zivver account is created, suspended or deleted. If an user is active, has an email addres, name and ZivverAccountKey, a Zivver account will be created if there is no current account for that email address. Suspended AD users can get suspended or deleted it Zivver, depending on the synchronisation options. Choose which boolean you want to use and for every user fill in either 1 or 0, TRUE or FALSE, yes or no.

Delegates

• Example syntax: john.doe@example.com;jane.doe@example.com

Delegates get full access to the Zivver inbox of a personal account. The filled in email addresses must have an active Zivver account in your Zivver organization, and the domain of the email addresses must be claimed in Zivver. If the delegate does not have an active Zivver account, is not a member of your Zivver organization or has an email address under a domain that your Zivver organization has not claimed in Zivver, then the Delegates property will be ignored.

Aliases

• Example syntax: alias@example.com;secondalias@example.com

If a Zivver message is sent to an alias, then the Zivver message is delivered in the inbox of the primairy email address. The filled in email addresses in the Aliases column must be claimed in Zivver. If the filled in email addresses at Aliases has received a Zivver message before creating the alias via the Zivver SyncTool, then the alias property will be ignored. In such cases, you should merge accounts before the next synchronisation.

Smtp-addresses that are not claimed in Zivver should be excluded from synchronisation to Zivver in the Zivver synctool. If you want to synchronise email aliases to Zivver for unclaimed domains, you should first claim the domain in Zivver.

OU UID

• Example syntax: / or

This is a mandatory field. Fill in / if your organization does not use Organizational Units in Zivver. The forward slash / puts users in the Root OU. Users reside in the root OU when your organization does not use Organizational Units in Zivver. If your organization does use Organizational Units in Zivver, then fill in a OU UID for each user. The value filled in in this column determines in which Organizational Units a user will be placed. A user can only be in one Organizational Unit at the time.

Example and further steps

The table below contains a filled in example. Note how the temporary password is empty. This means the SyncTool will randomly generate passwords and will ask you to save the temporary passwords to a file after the synchronisation is complete.

E-mail	Full name	Temporary password	Mobile phone	Is active	Delegates	Aliases	OU UID
john.doe@example.com	John Doe		+44 1234 567890	1	jane.doe@example.com	john.d@example.com	/
jane.doe@example.com	Jane Doe		0044 7890 123456	0		jane.d@example.com	/

After completing the Excel file, you can add functional accounts in the same file or continue and synchronise only personal accounts. Adding functional accounts to the same Excel file lets you synchronise both personal accounts and functional accounts with just one SyncTool profile.

• Add functional accounts to the Excel file.
• Do not add functional accounts and synchronise only personal accounts.

Functional accounts

This section explains how to synchronise functional accounts to Zivver from an Excel file (.xlsx) using the SyncTool.

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

1. In Source to use to sync users with Zivver select Excel file (xlsx) or Comma or Tab Seperated file (csv) from the dropdown menu.
2. If you have not done already in the previous sections, download the Excel file template by clicking Download template Excel File by clicking here.
   You will be asked to save an .xslx file named Zivver Users import template.

In the Excel file there are five columns (GroupName; GroupEmailAddress; GroupMembers; OU UID, aliases) in the second tab Groups. Use one row for each functional account and fill in the properties for each column. Down below is a description of what each column means and which syntax is expected.

GroupName

• Example syntax: Helpdesk

This field is mandatory. The GroupName is displayed as the name of the functional account. The GroupName will be displayed in a Zivver notification message, therefore you should enter the name in a way that matches how your organisation displays names to external recipients in normal emails.

GroupEmailAddress

• Example syntax: helpdesk@example.com

This field is mandatory. Functional accounts must have an email address. You can not enter email aliases or delegations through this method, only enter the primary email address. Enter aliases manually.

GroupMembers

• Example syntax: john.doe@example.com;jane.doe@example.com

This column should contain per functional account each personal accounts that should have full access permission. Email addresses of the personal accounts are separated by a semi-colon. If you leave this column blank, functional accounts are created without access permissions. You can enter access permissions manually in the WebApp. Currently it is only possible to delegate full access permission to a functional account.

OU UID

• Example syntax: / or

This is a mandatory field. Fill in / if your organization does not use Organizational Units in Zivver. The forward slash / puts users in the Root OU. Users reside in the root OU when your organization does not use Organizational Units in Zivver. If your organization does use Organizational Units in Zivver, then fill in a OU UID for each user. The value filled in in this column determines in which Organizational Units a user will be placed. A user can only be in one Organizational Unit at the time.

Aliases

• Example syntax: alias@example.com;secondalias@example.com

If a Zivver message is sent to an alias, then the Zivver message is delivered in the inbox of the primairy email address. The filled in email addresses in the Aliases column must be claimed in Zivver. If the filled in email addresses at Aliases has received a Zivver message before creating the alias via the Zivver SyncTool, then the alias property will be ignored. In such cases, you should merge accounts before the next synchronisation.

Smtp-addresses that are not claimed in Zivver should be excluded from synchronisation to Zivver in the Zivver synctool. If you want to synchronise email aliases to Zivver for unclaimed domains, you should first claim the domain in Zivver.

Example and further steps

The table below shows a filled in example:

GroupName	GroupEmailAddress	GroupMembers
Helpdesk	helpdesk@example.com	john.doe@example.com;jane.doe@example.com

Go to Synchronise users and groups to start the synchronisation.

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 it to the current Zivver accounts.
3. If you want to synchronise personal accounts, check the boxes [X] new users in local data to be added to Zivver and [X] users with changed information to be updated in Zivver under Personal accounts sync options.
   This will create new personal accounts and update information of existing personal accounts when available.
4. If you want to synchronise functional accounts, 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 when available.
5. Check the box [X] users that are in Zivver but not in local data to be modified.

6. Select Suspend the accounts of missing users (Recommended).
   This will suspend Zivver accounts when they are deleted from the Excel file or when the IsActive state is FALSE, 0 or no in the Excel file.

   It is recommended to suspend Zivver accounts instead of deleting Zivver accounts. Deleting an account results in losing access to all Zivver messages sent and received by that account. Additionally, disabling an account can be reverted, while deleting a Zivver account can not be reverted.

7. Leave the other boxes unchecked.
   You are now ready to synchronise Zivver accounts.

8. Click Run synchronisations.
   A Confirm actions pop-up appears with a summary of what is about to be synchronised.

9. Click Yes.
   A Get changes pop-up will appear.

10. Click Yes.
    A summary of the mutations will appear.

11. Click OK.
    A Save As pop-up will appear. If users do not log in via SSO, then make sure to save the file because it contains the Temporary Passwords for the newly created accounts. The default file name is M-D-YYYY - New Users Added To Zivver.
    After saving the file the SyncTool will notify you if the export was successful.

12. Click OK.
    The synchronisation is complete.

How to automate the SyncTool synchronisation using the Windows Task Scheduler