Synchronising personal and functional accounts from an Excel file

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.

Use one SyncTool profile to synchronise both personal accounts and functional accounts when using an Excel file. The Excel file template contains two tabs. The first tab is used to synchronise users, the second tab is used to synchronise functional accounts.

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.

Personal accounts when using SSO

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

If SSO is not configured for you organisation the accounts created by the SyncTool will be created with a temporary password. This means users have to know the temporary password created by the SyncTool and enter their temporary password at first login. You do not want to create accounts with temporary passwords when using SSO, because password management should be handled by the Identity Provider.

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. Enter aliases manually.

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
Only synchronise mobile phone numbers to ZIVVER.

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.

A user will not receive a text message after synchronising their mobile phone number via de SyncTool.

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, disabled 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. Disabled AD users can get disabled 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 provide full access to 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 by your organization in ZIVVER. If the filled in email addresses at Aliases has received a ZIVVER message before creating the alias via the ZIVVER SyncTool or the aliases’ domain is not claimed by your organization in ZIVVER, then the alias property will be ignored.

OU UID

  • Example syntax: / or <name OU UID>

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.

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 synchronise accounts from an Excel file without using SSO you will create accounts with a temporary password. A user will have to enter his temporary password at his first login attempt and will then be prompted to create his 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.

Temporary passwords are not stored when using the Windows Task Scheduler for automated synchronisation. This means you can’t provide the user with his temporary password. It is not recommended to use the Windows Task Scheduler for automated synchronisation when you use an Excel file as SyncTool input.

Mobile phone

  • Example syntax: +44 1234 567890 or 0044 1234 567890
Only synchronise mobile phone numbers to ZIVVER.

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, disabled 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. Disabled AD users can get disabled 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 provides full access to ZIVVER inbox of the personal account for the filled in email addresses in this property. 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 filled in email addresses at Delegates do not have an active ZIVVER account, do not belong in your organization or fall under a domain that is not claimed in ZIVVER for you organization, 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 by your organization in ZIVVER. If the filled in email addresses at Aliases has received a ZIVVER message before creating the alias via the ZIVVER SyncTool or the aliases’ domain is not claimed by your organization in ZIVVER, then the alias property will be ignored.

OU UID

  • Example syntax: / or <name OU UID>

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.

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 four columns (GroupName; GroupEmailAddress; GroupMembers; OU UID) 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 <name OU UID>

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:

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 Disable the accounts of missing users (Recommended).
    This will disable 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 disable 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

Common error message 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?

If you get the above error for one or more accounts there are two possible causes:

  1. The account has an email address that does not belong to a claimed domain in ZIVVER. Go to domains in ZIVVER and claim the domain, if you want to create a ZIVVER account for that domain.
    Claim a domain manual
  2. A ZIVVER account for this email address already exists, but it was created as a free account before your domain was claimed in ZIVVER. Go to domains in ZIVVER. There should be an Adopt button, if there are free accounts outside of your ZIVVER organisation. This button will adopt all accounts using the claimed domain and currently exist outside of your ZIVVER organisation.

    Adopted accounts are not transferred to your organisation immediately, because adoption of accounts into your organisation cannot be forced. It requires the user to log into ZIVVER before their account is adopted. If the Adopt button has already been used, you will see an hourglass hourglass_empty indicating the adoption is in progress and waiting for the user to log in.

Was this article helpful?

thumb_up thumb_down