Admin Guide: Mail Client Agent - Outlook profile creation

Overview:

About this guide
1. Audience
2. Using this guide
Product description
Standalone mode (command line operation)
1. Installation
2. Operation
  1. Parameters
Managed by the Cloudiway platform
Troubleshooting

1. About this guide

1.1. Audience

This guide is aimed at system administrators who need to configure the Outlook profile for their users, so that it functions after a mail migration to Office 365 (Exchange online) or to Exchange on premises.

1.2. Using this guide

This guide explains the functionalities and steps to follow to successfully configure Outlook profiles.

It uses the domain drypizza.com as an example for an Office 365 tenant. It also uses warmsushi.com as an example of a non-Office 365 system.

The screen dumps used in this guide reflect these business names to provide typical examples of data to enter into each field.

Whitepapers and guides covering Cloudiway’s other products, such as general mail migration, are available from the Cloudiway website (www.cloudiway.com).

2. Product description

2.1. General principles

The Mail Client Agent, previously known as Outlook Configurator, is a software utility that executes locally on the computer that has Outlook installed, to configure the Outlook profile.

It can configure profiles for Exchange or Office 365 (Exchange online). Supported versions of Outlook are 2016 and 2013 32bit and 64 bit.

What it does: it creates a new profile that points to the destination mailbox post migration. There are two possible ways of using it:

– Stand alone. You launch the program with specific parameters on a computer. It then immediately applies the given parameters and creates the new profile.
– Managed by the Cloudiway platform. The administrator remotely deploys the Mail Client Agent from the Cloudiway Platform. (Click Once must be enabled on the browser).

2.2. Details

The utility creates a profile for the provided email address, with the Cached Exchange Mode property activated, using an OST file for cached content.

2.3. Pre-requisites

– Microsoft Windows operating system
– .Net framework 4.5 or more

2.4. Supported Outlook versions

– Outlook 2013
– Outlook 2016
– 32 bit and 64 bit

3. Standalone mode (command line operation)

3.1. Installation

– Download the package at http://apps.cloudiway.com/download/mailclientagent.zip
– Unzip the package – Open a Windows command prompt
– Navigate to the location where the package has been unzipped
– Run the command-line utility mailclientagent.exe with the parameters as described below

3.2. Operation

3.2.1. Parameters

Here is the list of parameters required by the program:

3.2.1.1. Outlook 2016

Outlook 2016 requires only these parameters to configure the Outlook profile: (it is using autodiscovery for discovering the servername).

– email user@company.com (email of profile to create)
– displayname “Firstname Lastname”
– isdefault (if omitted = false)

Example: MailClientAgent.exe -email chloe@drypizza.com -displayname “Chloe Page” -isdefault

Here is the output: Once the profile is created, the user is prompted for his password the first time he opens Outlook. Outlook then synchronizes content from the Exchange server to the local .ost file.

3.2.1.2. Outlook 2013

The creation of the profile for Outlook 2013 requires more information. It needs the ExchangeGuid for the mailbox, and the server url.

You can get the ExchangeGuid property value by using the PowerShell cmdlet Get-Mailbox:

Get-Mailbox chloe | fl, ExchangeGuid

Here is the list of parameters for configuring Outlook 2013:

-email user@company.com (email of profile to create)
-displayname “Firstname Lastname”
-exchangeguid “exchangeMailboxGuid”
-server ServerName (outlook.office365.com for Office365)
-isdefault (if omitted = false)

Example: MailClientAgent.exe -email chloe@drypizza.com -displayname “Chloe Page” -exchangeguid “323F79DA-6D3E-41BF-9FC1-C1A67A02B837” -server outlook.office365.com -isdefault

4. Managed by the Cloudiway platform

4.1. Description

The managed way of using the MailClientAgent program is different from the standalone usage described above.

The central point is the user list that is on the Cloudiway platform at https://apps.cloudiway.com under Mail Migration/Mail Client List. From this list the project administrator can perform and monitor all actions: Install, Audit and Configure.

4.2. Users list

The Mail Client User List is the list of all profiles that need to be configured for Outlook.
For each user in the user list these properties are defined:

First name, Last name: used to build the display name in the Outlook profile as “Firstname Lastname”
Source email, used by the platform to send out an email for agent installation.
Target email, the email used to configure the Outlook profile.

The first step in setting up the Mail Client Agent feature is to create the list of users. There are two ways to add users to the list:

CSV file upload;
Creation of single users.

4.2.1. Option 1: CSV upload

If you have a CSV file of all your users, you can upload the file to Cloudiway. The file must have the following fields in the header row:

FirstName;LastName;SourceEmail;TargetEmail;BatchName

The platform does not check for duplicate entries, so be careful when you create your csv files.

The BatchName field can be left blank. If required, you can use this field to name different batches so they can be run in a certain order. A sample CSV file is available for download during the steps outlined below.

Under Mail Migration, go to Mail Client List
Click on Manage in the bottom left corner and select Upload CSV
If required, click on Download sample CSV and add your users to the CSV file using the sample headers (FirstName;LastName;SourceEmail;TargetEmail;BatchName)
When you have a complete CSV file with the correct headers, click on the bigger Upload button
Locate your CSV and double-click on it to select it
Click on the Upload button in the bottom right corner.
If the CSV file format is not correct, you will see an error message on your screen:
If you see any error messages, check your CSV file to ensure it has five columns, each with a separator (including the last) and try uploading again
Once the CSV file format is correct, you will see a confirmation message at the top of your screen:
Check your email. When you have received confirmation that the upload has been completed, you can refresh the Cloudiway platform to display your imported users

4.2.2. Option 2: Single user creation details

Many of our first-time customers create a single user for testing purposes. This provides a means of testing the features without affecting all users. Single users can also be created for migrations affecting just a few users.

Go to the Mail Client List of the Mail Migration menu
Click on Manage in the bottom left corner and select Create Single to display the following screen:
Fill in all details for a new user
Click on the Create button
The new user will be added to the Mail Migration / Mail Client List screen:
Repeat steps 1 to 4 for any more users you’d like to create

4.3. Actions

From the user list, the project administrator can perform various actions:

schedule the installation of the agent,
schedule a computer audit on the computer where the agent is installed,
schedule the creation of the Outlook profile on the computer where the agent is installed.

4.3.1. Schedule agent installation

The first action that must be performed for a user is the installation of the agent on the local computer.

This is done with ClickOnce, a Microsoft technology. ClickOnce enables the user to install and run a Windows-based client application by clicking a link in a web page.
When the project administrator chooses the “Install” action for all users or a subset of users, then an email is sent out to the source email address of all selected users. Each email message contains a link the user must click to install the agent locally.

When an agent is locally installed, it connects to the platform to report it has installed. The status appears as “Installed” in the Mail Client users list. It is then listening to commands it gets from the platform.
When the agent is installed, then the project administrator can choose between 2 new actions: Audit and Configure.

To schedule the installation of the agent, go through the following steps:

Select the users or batch in the Mail Client List for which you want the agent to get installed.
In the bottom bar choose Actions and then Install.
Here is the content of the email that is sent to the user’s source email address:

4.3.1.1 Installation on the user’s computer

Here are the steps for the installation of the agent on the user’s computer:

After receiving the email above the user must click on the Mail client agent link in the message.
The link brings the user to this page:
With Microsoft Internet Explorer, the ClickOnce technology is already embedded in the browser. Google Chrome or Mozilla Firefox require an additional extension, plugin or add-on to be installed. The links to the extensions are provided in the message on the page. For Firefox we recommend FxClickOnce. For Chrome we recommend Meta4 ClickOnce Launcher.
After installing the plugin if necessary, check the checkbox confirming that requirements are installed. Then click Start:
Click on the button ClickOnce Install in the popup window.
You get a security warning:
When you click Install the program installation starts. Once installed the agent starts and connects to the platform to listen to requests.

4.3.1.2 Uninstallation on the user’s computer

If you need to manually uninstall the Mail Client agent follow these steps:

Go to Control Panel/Programs and Features
In the list of installed programs locate the program with Name MailClientAgent and Publisher Cloudiway. Right-Click on the line.
Choose Uninstall/Change
Click OK on the following screen:
The program is entirely removed from the computer.

4.3.2. Schedule computer Audit

The first step is to select users or a batch/batches in the Mail Client List.
You choose to schedule the audit of the remote computers by then hitting Audit in the Actions menu item in the bottom bar:
This action sends a command to the agent to perform an Audit of the computer it resides on. Audit collects several data:
a. Office version and bitness, as well as the install path on the hard drive.
b. System bitness, cpu speed, available disk space on each drive, installed RAM and available RAM.
c. List of installed browsers with bitness and version.

To view audit results simply click on the user in the Mail Client List.

4.3.3. Schedule Outlook profile configuration

Choosing Configure in the Actions menu item in the bottom bar sends a command to the agent to perform the creation of the Outlook profile.
The creation of the Outlook profile is the same as in the stand-alone command line version of the agent. It uses the user’s target email, as well as first name and last name for the profile’s display name.

Attention: There are two different cases: Outlook 2016 and Outlook 2013.

Outlook 2016: nothing more than the previously described steps is necessary.
Outlook 2013: the agent needs the Exchange Guid of the mailbox to configure the profile. The steps to get the Guid for each target mailbox in the Mail Client List are described in the next chapter.

4.3.4. Important pre-requisite for Outlook 2013 profile configuration

We provide a feature that collects Exchange Guids for all target mailboxes in the Mail Client List. This is a mandatory step before Outlook 2013 profile configuration.

2 steps are required to launch the feature:

Create a Mail migration target connector with a domain name that matches the domain of target emails
Launch the Global Action Client Agent Preprocessing

Here is the detail of each of these steps:

4.3.4.1. Create your Office 365 or Exchange target connector

If you already created a target connector for the mail Migration you can skip this step.

Otherwise go through these steps:

From your browser, go to https://apps.cloudiway.com and login
Click on Mail Migration on the left, then Targets
Click on the + New option at the bottom of the screen
Click on Office 365 and type a meaningful name in Connector name
Click on the Create button
Type your target domain name in Domain. This is the domain that will be matched with the target emails domain in your Mail Client User List.
Type your Office 365 account credentials (with administrator and impersonation rights)
The remaining field is for archiving older emails from inboxes (switched off by default):
For now, click on the Save button without activating this option (it’s only meaningful for mail migration. Please refer to the Admin Guide for the migration scenario you need to perform to get detailed information on how to use the parameter).

4.3.4.2. Launch the Global Action Client Agent Preprocessing

Once the target Office 365 or Exchange connector is created you can go ahead and launch the Global Action Client Agent Preprocessing. For this, go to Mail Migration; then Global Actions and hit the Client Agent Preprocessing button.

This process is fast. It uses Microsoft PowerShell. The necessary credentials are taken from the previously defined target connector and it gets the Exchange Guid for each target email in the Mail Client User List.

Here is the display once done:

Once the preprocessing is done for Outlook 2013 users, you can go back to the Mail Client User List and launch the Outlook profile creation for the users.