Converting 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 of March, 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!

Why is this necessary?

In order to better protect individual rights to privacy (and 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 the user Andreas Knecht, can be identified by its username and user key - andreask. Going forward this will no longer be possible and the only valid identifier allowed by Atlassian APIs will be the accountId, which for this user would be 557058:5aedf933-2312-40bc-b328-0c21314167f0.

This means that all Cloud apps (including 'Automation for Jira'), have to switch all stored configuration to use the new accountId instead of usernames and user keys.

In most cases we've done the heavy lifting for you and already converted all your Automation rules to use the new accountId user attribute when communicating with Jira's APIs. However there are some cases where we can not automatically convert your rules, where these rules use specific user smart values.

We will identify all rules where this is the case and notify you ahead of the 29th of March. Please use this guide to help you convert your rules to be compatible.

Converting user smart-values

What will break after the 29th of March?

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

  • 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

Currently this will render the username at runtime and produce:

Hi andreask, Please respond. Cheers Automation

After the 29th of March this will now render:

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

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

Converting smart-values

After the 29th of March, 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 March)
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:

// INCORRECT: This returns the user's username, not full name
{{reporter.name}}  

// CORRECT: renders user's full name: Andreas Knecht
{{reporter.displayName}}                  
// CORRECT: renders user's first name: Andreas
{{reporter.displayName.split(" ").first}} 

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), then you should use:

{{reporter.accountId}}  

After the 29th of March, these usernames and keys will simply cease to exist so if your third party integrations depend on them, then they'll have to be re-written to accept user account ids before this date.

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

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 March?

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 March these JQL searches will fail and no longer return valid results. All username's will have to be replaced by their corresponding account ids.

Converting JQL

JQL will be auto-converted

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 March.

The JQL above would become:

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

This is obviously not very user friendly since 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 (11th of 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