Overview
A new tab /5. User Mapping/ now appears on the ALM Connection. From this tab you can manage how piplanning.io handles user mapping which links a piplanning.io User account to the matching User account in your ALM tool (Jira/ Rally).
Once a user mapping is completed, then piplanning.io can sync the Reported By and Assignee/Owner fields in both directions between piplanning.io and the ALM tool.
Each ALM Connection has its own User Mapping. If you have more than one ALM Connection, a separate User Mapping is handled by each ALM Connection (because the ALM Connection can be used in different PI Sessions).
How to: set up the User Mapping Settings
Go to RTE Cockpit > ALM Connection and select edit on the ALM Connection you want to configure.
Open tab 5. User Mapping. This is the last step after 1). Connection, 2). WebHook, 3). Team Mapping and 4). ART Mapping tabs.
Select either option or both options, both checkboxes can be selected*, under the heading: How piplanning.io users are mapped to Jira users:
By e-mail (automates the User mapping between piplanning.io and Jira)
Manual (manual override to allow for different emails in both systems)
User Mapping Options Explained
☑️ By E-mail
When a user logs in to piplanning.io, if their User account is not yet mapped to their User account in Jira, then piplanning.io will attempt to automatically match the Users email to the Jira or Rally User with the same e-mail address.
How By E-mail mapping works:
Each login starts a mapping attempt for every ALM Connection where that user is not yet mapped.
If an attempt fails, for example because no ALM user with that e-mail address exists, it is retried at every later login until it succeeds.
Users who are already mapped are not mapped again.
IMPORTANT:
The By E-mail setting is best for organisations where users have the same e-mail address in piplanning.io and in the connected Jira instance (ALM Connection).
Note: Failed mappings are retried at every login. If many users can't be matched, this can produce a large number of requests to your Jira or Rally instance. Before you enable this option, check that users' e-mail addresses are the same in both systems.
IMPORTANT
Do NOT enable the automated User Mapping > By Email option on ALM Connections that are used to connect to test instances of Jira or where the e-mail addresses of the users are not the same in both systems (Jira and piplanning.io.
Note: In Jira Cloud, a user's e-mail address may be hidden by their Atlassian profile visibility settings. Users whose e-mail address is hidden can't be mapped by e-mail and should use Manual mapping.
☑️ Manual
Each user picks their own Jira or Rally account on their piplanning.io Profile page.
To complete the ALM User Mapping on your piplanning.io User Profile:
In piplanning.io, open the User Profile page by click on the User avatar > Profile in the top right after logging in.
Click on the ALM Mapping tab on the Profile page.
Follow the instructions in the ALM User Mapping article here.
The Manual setting is best for: Organisations where e-mail addresses differ between systems (for example, aliases or separate domains), or where e-mail addresses are hidden in Jira.
What Data Fields Get Synchronized with User Mapping
Once a user is mapped, these fields sync in both directions:
piplanning.io | Jira | Rally |
Reported By | Reporter | Created By |
Assignee | Assignee | Owner |
Unmapped Users
Users without the User Mapping completed on the respective ALM Connection used in a PI Session, will not be able to have the Reported By and Assignee fields synchronized between the two tools. To fix this:
By e-mail: correct the e-mail address so both systems match. The mapping will be attempted again at the user's next login.
Manual: ask the user to select their ALM account on their Profile page. You can monitor and manage what User Mappings are incomplete using the reporting option provided on the page. Please see below for more details.
Managing Unmapped Users
If you wish to manage the Users accounts that missing the User Mapping, use the Export Users button in the top right corner of the page.
This User export will provide a *.xlsx file that lists all the piplanning.io Users and filter on those User accounts that do not have the ALM User Mapping complete. You can also view any of the valid reasons for why the ALM User Mapping remains unmapped.
Unmapped Reasons | Description |
No Jira user | No Jira user found with this e-mail address. |
Jira E-mail hidden | Jira returned users but hid their e-mail addresses, so none could be compared. |
Multiple Jira Users | The e-mail matched more than one Jira user, so the match is ambiguous. |
Jira User Taken | The Jira user with this e-mail is already mapped to another piplanning user. |
Mapped to No User | The user mapped himself explicitly to 'no Jira user'. |
Unused | The user is not assigned to an issue neither in piplanning.io nor in Jira. |
Frequently Asked Questions (FAQ's)
Q: Does User Mapping create users in Jira or Rally?
A: No. It only links accounts that already exist.
Q: Do I need to remap users if I change the mapping option?
A: Existing mappings are preserved if these settings are changed.
Q: Why hasn't a user been mapped yet with By E-mail?
A: User Mapping only happens when the user logs in, and if the emails match. Users who have not logged in since the option was enabled remain unmapped.
Related articles
Setting up an ALM Connection to Jira
Setting up an ALM Connection to Rally