External ID Management - FAQs and Troubleshooting

Martin Felcman

Updated July 15, 2024 19:51

Productboard Product Team

In this article, we explore the exact logic regarding how Productboard manages email addresses and external IDs.

What is External ID and why would I want to use it?

External IDs, often called User IDs, are unique user identifiers that won't change. You may wish to send these to Productboard instead of, or in combination with an email address.

One reason to do this is that while the user's email address is subject to change in most apps, you can control the unique identifier that is sent to us, therefore maintaining a consistent user record in Productboard even if the user changes their email address.
Additionally, you can use external IDs if you are very concerned with user privacy and do not want to send an email address to Productboard.
You may not store email addresses in all of your tools. Therefore, bringing External IDs to Productboard will enable you to use other integrations that bring in customer data (e.g. ingesting Amplitude cohorts).

This External ID will likely be consistent across your applications. For example, a user would be identified by the same external ID in your database, CDP (e.g. Segment.io), support tool (e.g. Zendesk), and product analytics platform (e.g. Amplitude).

Insights integrations supporting the ingestion of external IDs can also encounter a conflict. However, when processing data coming from a third-party system via an Insights integration, Productboard is much more lenient and handles conflict scenarios in such a way that the processing never fails. This is important since Insight automation typically uses webhooks and the inter-system communication is fully automated, with no human to delegate the conflict resolution to.

For more details on why external IDs are useful, or how to use them within Productboard, click here.

Identifying unique users

With the addition of external IDs, we have added yet another unique identifier to Users. This means that both external IDs and emails are individually required to be unique within a space.

What if I don’t use external IDs?

If you currently use emails to identify your users in Productboard and do not intend to use external IDs, nothing will change for you. Your Productboard experience will remain unchanged.

What if I don’t use emails?

If you don’t have any emails in Productboard and you only intend to use external IDs to identify your users, then remember that external IDs are unique. Two users cannot have the same external ID.

What if I use both emails and external IDs?

We support you using both external IDs and email addresses. However, emails and an external ID both require uniqueness. Therefore, using both can sometimes lead to conflicts.

Context dependant, Productboard handles such situations differently. No issues should emerge, but

Importing External IDs through our Users API

Using our Users API, you can apply external IDs to your existing Productboard users.

While manipulating User via the User API, it can happen that you:

Try to set an external ID to a user, but that external ID is already taken by another user.
Try to set an email address to a user, but that email address is already taken by another user.

In both cases, the API requests fail, rejecting such an update. It is up to you to decide how to resolve the situation.

Insights integrations

This is how Productboard handles individual conflict scenarios when processing data incoming via an Insights integration:

Scenario #1:

Conditions:

Incoming data contain both an external ID (id123) and an email (email123).
A user u exists in Productboard having external ID = id123, but email = email123

Resolution: The newly created note is attributed to User u.

Explanation: For Productboard, matching external IDs are the strongest match and the email mismatch is simply ignored as we consider the users to be the same based on their matching external IDs.

Scenario #2:

Conditions:

Incoming data contain both an external ID (id123) and an email (email123).
A user u exists in Productboard having no external ID and but email = email123

Resolution: The newly created note is attributed to User u. Also, User u is updated and their external ID is set to id123.

Explanation: We consider this a “missing external ID” scenario and backfill the external ID for you based on matching email addresses.

Scenario #3:

Conditions:

Incoming data contain both an external ID (id123) and an email (email123).
A user u exists in Productboard having email =email123, but external ID = id123

Resolution: A new User u2 is created having no email address (to prevent collision with u) and external ID = id123. The newly created note is attributed to user u2. Also, the new User u2 is assigned to the same company as user u (if any).

Explanation: This is the best Productboard can do in such a situation to make sure the processing doesn’t fail. Productboard doesn’t have enough information to be able to reliably determine the desired state. Therefore, we rather create a new user with the incoming external ID and attribute the note to them. We also carry over the company assignment from the conflicting user as we assume these two users should likely be the same user, but there’s an inconsistency in the data.

This is preferable to attributing the note to nobody as the newly created User u2 will be picked as a match for any subsequent notes coming from any integration with the same external ID. You can also merge users manually later to resolve this duplicity.

Therefore, it is important that before you import external IDs, you ensure that you have the appropriate external ID in each system.

Any other case:

In all the other cases, Productboard is either able to identify the user unambiguously and thus attributes the note to them, or no user can be found using incoming data and a new user is created prior to the note being attributed to them.

Notes API

The Notes API historically allows creating users. The process of matching or creating users based on the incoming data is exactly the same as the one used by Insights integrations, with one major difference:

Wherever Insights integrations do any conflict resolution to prevent the incoming request from failing, the Notes API simply fails. This is consistent with how the User API works and the way our public API behaves in general.