Convert usernames to user account ids (EU GDPR)

Warning: Breaking API changes due to EU GDPR

Due to the European General Data Protection Regulation (GDPR), Atlassian are changing a number of user-related APIs.

These changes affect Automation for Jira in cloud, and require some changes to rule configurations, otherwise your rules may break after the 29th April 2019!

Who this guide is for?

You will only be affected by these API changes, if you are using Jira Cloud and one of the following:

  • JQL searches with usernames (e.g. reporter = andreask)
  • Smart values that access deprecated user fields (e.g. {{reporter.name}} - see below for a full list)

If you are using Jira Server, or you are not using JQL, or smart values like the above, then you can safely ignore this guide.

Please use this guide to help you convert your rules to be compatible.

Why is this necessary?

To better protect individual rights to privacy (in particular, the right to be forgotten), Atlassian are changing all of their Cloud APIs to identify users by anonymous account ids instead of usernames.

For example, user Andreas Knecht can be identified by username and user key - andreask. Atlassian APIs only accept the accountId as a valid identifier, which for this user, would be 557058:5aedf933-2312-40bc-b328-0c21314167f0.

In most cases we've done the heavy lifting for you and already converted all your automation rules to use the accountId user attribute when communicating with Jira's APIs. However, rules that use specific user smart values can't be automatically converted.

Converting user smart values

What will break after the 29th of April?

Any user system field (reporter, assignee, or customfield), that's using the following user properties may break or lead to undesirable results:

  • Default value (returns the username):

    • {{reporter}}
    • {{issue.assignee}}
    • {{issue.My user custom field}}
    • any other issue field containing users...
  • User key:

    • {{reporter.key}}
    • {{issue.watchers.key}}
    • {{issue.My user custom field.key}}
    • any other issue field containing users...
  • Username:

    • {{reporter.name}}
    • {{issue.creator.name}}
    • {{issue.My user custom field.name}}
    • any other issue field containing users...

For example if you had configured an 'Add comment' action with this comment body:

Hi {{reporter.name}}, Please respond. Cheers Automation for Jira

Currently this will render the username at runtime and produce:

Hi andreask, Please respond. Cheers Automation for Jira

After the 29th of April this will now render:

Hi 557058:5aedf933-2312-40bc-b328-0c21314167f0, Please respond. Cheers Automation for Jira

This is not ideal, so these smart values should be converted as follows.

Converting smart values

After the 29th of April, user smart values will operate in the following manner (note: the same applies to all user fields):

Type Example Old value New account id value (after 29th of April)
Default {{reporter}} andreask (username) 557058:5aedf933-2312-40bc-b328-0c21314167f0
Username {{reporter.name}} andreask 557058:5aedf933-2312-40bc-b328-0c21314167f0
User key {{reporter.key}} andreask (user key) 557058:5aedf933-2312-40bc-b328-0c21314167f0
AccountId {{reporter.accountId}} 557058:5aedf933-2312-40bc-b328-0c21314167f0 557058:5aedf933-2312-40bc-b328-0c21314167f0
Display name {{reporter.displayName}} Andreas Knecht Andreas Knecht

Depending on the usage, your existing smart values need to be converted in different ways.

Incorrect usage of usernames

We've seen many smart values, incorrectly using user names (default value or .name) instead of the users's full name.

These should be changed to:

{{reporter.name}} - INCORRECT: This returns the user's username, not full name
{{reporter.displayName}} - CORRECT: renders the user's full name: Andreas Knecht
{{reporter.displayName.split(" ").first}} - CORRECT: renders the user's first name: Andreas

For other usages it depends on your use of the smart value. If you need to uniquely identify the user for an API call (e.g. in JQL searches, in advanced JSON under 'More options', or an outgoing web hook), use:

{{reporter.accountId}}

Mentions in wiki markup

At the time of writing (21 of Feb 2019), mentions in wiki markup will also have to be converted:

Hi [~{{assignee}}] - INCORRECT
Hi [~accountid:{{assignee.accountId}}] - CORRECT

Ideally this should not be necessary and mentions like [~username] should just work once they become [~accountId].

However due to a bug with wiki markup (ACJIRA-1715) the above conversion is currently necessary. Mentions will have to be prefixed with [~accountid:<accountid>] if they are using the user's account id.

Advanced field values (JSON)

Referencing user fields in cloud (such as reporter, assignee, etc.) now requires the property "id" to be set with a user's account id
rather than using "name"

These values will have to be converted as follows:

// INCORRECT: This will stop working since {{initiator.name}} will no longer
return usernames
{
    "fields": {
        "assignee": { "name": "{{initiator.name}}" }
    }
}

// CORRECT:
{
    "fields": {
        "assignee": { "id": "{{initiator.accountId}}" }
    }
}

Converting JQL

What will break after the 29th of April?

Currently it is still possible to search for JQL containing usernames. E.g. this is a valid JQL string that can be used in our JQL condition:

reporter = andreask and assignee in (fred, barney)

After the 29th of April these JQL searches will fail and will no longer return valid results. All username's will have to be replaced with their corresponding account ids.

Converting JQL

Auto-Convert JQL

Luckily Atlassian are providing an API to upgrade existing JQL to account ids. We are going to auto-convert all stored JQL searches to the new account id based format before the 29th of April.

The JQL above would become:

reporter = 557058:5aedf933-2312-40bc-b328-0c21314167f0 and
assignee in (5c00beb62434bf3a1a91d5d6, 123123adfafcadfd6)

This is not very user friendly as you can no longer identify which users are in the above JQL string. Entering a query like this is also quite difficult (you'd have to lookup the account ids of users via API calls).

Ideally Atlassian will provide a JQL autocomplete user interface control that will make this easier, however at the time of writing (21st Feb 2019), no such control has been provided.

As a result we've built some UI controls to help with entering and reading JQL queries.

Inserting an account Id

Insert user

Insert user 2

Resolving users in existing JQL

Resolve user