Summary

When migrating from Data Center to cloud, Atlassian has recommended best practices for preparing your environment. These are documented in our pre-check migration checklist for Jira and Confluence:

• Jira pre-migration checklist

• Confluence pre-migration checklist

One essential component of migration is the export and import of users from the source to the destination. For Atlassian Cloud, valid and unique email addresses are mandatory for every user. In this article, we will discuss how to resolve instances when there is a user account that is missing an email address.

Identify

Use one of the following ways to identify users with missing email addresses.

Identify users automatically in the Migration Assistant (Jira only)

You can use the Migration Assistant to assess your users and identify those whole email addresses don’t meet the requirements. Missing emails will be identified as invalid. You can complete this assessment at any time before migration.

To identify users with missing addresses:

1. Open the Jira Cloud Migration Assistant.

2. In the Assess and prepare users section, select Begin assessing. You’ll be moved to the page with empty results.

3. To start the assessment, select Begin assessing.

Once the assessment is complete, you’ll see the results, including invalid email addresses (including missing ones) and duplicated email accounts.

For more information about the assessment and next steps, see Assess and prepare your users for migration.

Identify users in the database

You can also identify users with invalid email addresses by running the following query in your database:

SELECT *
FROM cwd_user
WHERE (email_address IS NULL OR email_address = '')
OR (lower_email_address IS NULL OR lower_email_address = '');

The output of this query will identify all user records that have a missing email address. There are 2 columns in this table:

• email_address
• lower_email_address

Consider both of these columns when running SQL queries against the database as having one populated and another empty can cause unintended results.

Solution

You can either fix the email addresses manually in your source user directory or choose one of the automatic options from the Migration Assistant to update the users during migration.

Manually create valid emails and update them in your user directory

You can manually create email addresses that are valid (e.g. user@atlassian.com) and update them in your user directory, be it an LDAP Server or your Server or Data Center instance.

To update email addresses of users in your Server or Data Center instance:

1. Select Administration > User management.

2. Find the user you’d like to update using the filters at the top of the page.

3. Select Edit next to the username.

4. Update the email address, and select Update.

Automatically update users during migration (Jira only)

This option is only available in the Jira Cloud Migration Assistant.

After you complete the assessment described in the Identify users automatically in the Migration Assistant section, the Migration Assistant will let you fix invalid email addresses as the next step. Note that if you choose this approach, we won’t update users in your source directory, but only the ones we create in Cloud during migration.

These automatic fixes should be applied to unimportant accounts, such as old or testing ones. Actual users who'll be working in Cloud should be updated in your user directory.

To automatically fix invalid email addresses:

1. In the Migration Assistant, view the results in the Assess and prepare users section.

2. When viewing the results, select Fix invalid emails.

3. Choose one of the options to fix invalid emails. For more information on each option, see Fix invalid email addresses.

Update LDAP filters to exclude users with missing emails

In some cases the number of emails to fix is not trivial and would require significant effort and review. Missing emails often originate from service/non-human/department accounts, or from inactive users, in upstream user directories. After running the SQL query above, these users without emails can be filtered out. Note that they will no longer exist in the application, and will not be able to login.

1. Login to the application as a local system administrator, as it will not be possible to edit the current LDAP connection which you may have used to login.

2. Open up User Directories from the Settings menu (Jira - Configuring User Directories, Confluence - Configuring User Directories).

3. Click Edit in the Operations column against the relevant directory connection.

4. Scroll to "User Schema Settings" and expand the accordion.

5. Update the "User Object Filter" by nesting (mail=*) appropriately. For example, by changing it in the following way:

From:

(&(objectCategory=Person)(sAMAccountName=*))

To:

(&(objectCategory=Person)(sAMAccountName=*)(mail=*))

Next:

1. Click Quick Test and ensure you can login to your own account in another browser.

2. Once testing is complete, click Save and Test. After updating directory connection settings, the user base will be updated. You may run the SQL query above to validate if there are still missing emails.

Additional suggestions

If filtering out users without emails has not solved your problem:

• It is worthwhile speaking to your Active Directory/identity administrator to see if there are local custom attributes which can be used to identify users who do not have emails/should not be synchronised. This can be achieved by updating the Base DN.

• Users inactivated in Active Directory can be filtered out using Microsoft's userAccountControl parameter. Update your filter from:

  (&(objectCategory=Person)(sAMAccountName=*)(mail=*))

  to

  (&(objectCategory=Person)(sAMAccountName=*)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

  (userAccountControl:1.2.840.113556.1.4.803:=2)  defines all users who have been inactivated in Active Directory, so this filter keeps only active users (those who have not been inactivated).

See How to write LDAP search filters for further tips.

Manually update users in the database

In many cases it is not always possible to accomplish upstream fixes or update LDAP filters depending on a number of factors. An alternative method is to assign a temporary or placeholder email address that will allow the Migration Assistant to validate the users during its pre-checks and migrate your userbase successfully.

1. Generate a domain that can be used in the SQL query. In the example below, we are using http://domain.com . 

2. Generate a unique identifier for user accounts. In the example below, we are using user- and appending the user id value which should always result in a unique name. (user-1@domain.com, user-2@domain.com)

3. Execute one of the SQL queries below.

Postgres

UPDATE cwd_user
SET email_address = 'user-' || id || '@domain.com',
    lower_email_address = 'user-' || id || '@domain.com'
WHERE (email_address is NULL or email_address = '') or (lower_email_address is NULL or lower_email_address = '');

MySQL

UPDATE cwd_user
SET email_address = CONCAT('user-',id,'@domain.com'),
    lower_email_address = CONCAT('user-',id,'@domain.com')
WHERE (email_address is NULL or email_address = '') or (lower_email_address is NULL or lower_email_address = '');

Oracle

UPDATE cwd_user
SET email_address = 'user-' || id || '@domain.com',
    lower_email_address = 'user-' || id || '@domain.com'
WHERE (email_address is NULL or email_address = '') or (lower_email_address is NULL or lower_email_address = '');

MS SQL Server

UPDATE cwd_user
SET email_address = CONCAT('user-',id,'@domain.com'),
    lower_email_address = CONCAT('user-',id,'@domain.com')
WHERE (email_address is NULL or email_address = '') or (lower_email_address is NULL or lower_email_address = '');