When an engineer uses multiple identities to do their work, it is essential to get the identities merged, so that the engineer's work is reflected holistically and accurately. The merge tool helps you merge these identities together. Learn more about aliases and what they are.
When to merge users
Merging users is super important, so it’s important to stay on top of it. You should always look to merge users when:
- You add a new team member to your organization.
- When you commit data under a different alias that has not been imported into Flow.
- When you add new data sources to Flow (integrations, repos, PR projects, etc.)
You can also sign up to have an email alert you when new users have been added or when Flow has found some users that you might want to merge.
Recommendations to keep your user data clean (and limit the number of user merges you need to complete)
- Use a consistent account to contribute to your Git host and ticket system. If you and your team create many new accounts, or use different Git identities to commit code, you will generate new aliases that will need to be merged to your apex user
- Be aware of new integrations you add to Flow. Each new integration will generate a new alias for your users. Watch out, especially, for open source repos. If your team is contributing to them, then you may need to import them, but think twice if you’re just curious.
- When you hire a new employee, ensure to merge their aliases as soon as they have contributed to your Git host and/or ticket Integration.
How to merge user aliases (identities)
Step 1: Starting on your Flow home page, go to the top navigation bar and click Settings. Using the left navigation under User Management, click Users.
Step 2: Click Merge users in the top-right corner.
Step 3: From here, there are two options for merging user.
Option 1: Merge suggestions
The Merge suggestion tool is used when you don’t have a specific, problem user in mind, but want to keep your user base clean. The Flow system will review your user base and suggest users that are likely the same person.
You should check periodically for new suggestions, or configure the Admin alert emails to let you know if some come in.
Using the merge tool for merge suggestions.
There are three easy steps for reviewing suggestions:
Step 1: Select a suggestion from the list.
Steps 2 & 3: Review the selection and save or skip. You are looking at the list of users that Flow has suggested to merge together to see two things.
- Do they appear to be the same human?
- Has Flow selected the best user as the Target User. A target user is the user that will survive after the merge. You’re looking for:
- Whether the target user has a login and whether the merging users have logins.
- Whether the target user will be included or excluded from metrics.
- Whether the name and email for the target user are sensible.
You’re likely to see one of three things:
The suggestion looks good. All of the users in the suggestion look like the same person and the target user is fine. This should be most of the time.
The suggestion is junk. The suggestion has MANY DIFFERENT humans on the right side. This should be rare.
The suggestion is MOSTLY good.
A) Most of the users look like the same person, but maybe there are one or two that are not.
B) Maybe they all look like the same person, but the one selected for the target user isn’t the best one for some reason.
When the suggestion looks good, just Click Save and Next.
When the suggestion looks like junk, it’s recommended that you:
- Make a note of the distinct users the suggestion seems to represent. You’ll need to merge those manually. See Option 2, merging manually.
- Skip the suggestion.
When things are mostly right, use the workspace panel (the one on the right) to modify the suggestion before you accept it.
- If there are some users that don’t belong, you can remove them from the merge.
- If there is a user that is better for the target user, you can set as the target user.
Tips for merging large numbers of users
Tip #1: Use quick filters to take are of suggestions that matter most.
- Contain default domain - In order to use this filter you first need to set up your default domain under the Defaults tab. Once set up, this will show you only merge suggestions that contain aliases with your company email address.
- Aliases created in the last 30 days - This list will show you any alias that was recently created. This could help you locate new employees that recently started committing to your code base, and/or users that have recently been ingested from a new repo or Integration.
- Have multiple logins - This filter is helpful if you have enabled an SSO Integration and users may end up with multiple logins due to case sensitive email addresses.
Tip #2: Sort by the Merging users column and take care of the big ones first and then Select all on the rest. This works best if you setup your defaults settings (see Default configurations below).
Option 2: Manually Merging
This option will be best if you are trying to merge only a select few users, or if you want to check if there are any new aliases that were introduced to Flow that have yet to be merged.
Step 1: Start by clicking the All users tab.
Step 2: Then click and drag the user (that you would like to merge other users into) to the target user drop zone as depicted below.
Step 3: Select other users that you would like to merge using the check boxes, then click and drag them into the alias drop zone.
Step 4: Click Save to apply the merge to the user staged for merging.
Step 5: Success! You have manually merged aliases into a user. You can see all aliases associated with a user on the User detail page under the Aliases tab.
Under the Defaults tab you can set a preferred domain and integration for future merge suggestions. The merge suggestion tool looks for your company domain first if no company name is found, it looks to your preferred Integration.
In the bottom section you can also adjust the following merge suggestion configurations:
Exclude common words and emails from matching - You can edit the defaults and add any that are specific to your account.
Exclude first name matches - This can be helpful if there are multiple users that use the name “Chris” or “John”.
If you need help, please email firstname.lastname@example.org for 24/7 assistance.