Convert usernames to account IDs

 

The following guidelines outline how to convert user smart values and JQL to user account IDs, to address recent changes to how user data are handled within Jira Cloud.

Converting user smart values

What will break after 29 April 2019?

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 the following comment body:

1 Hi {{reporter.name}}, Please respond. Cheers Atlassian

This will currently render the username at runtime and produce:

1 Hi johns, Please respond. Cheers Atlassian

After 29 April 2019 this will now render:

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

Converting smart values

User smart values will operate in the following manner:

This will apply to all user fields.

Type

Example

Old value

New account id value (after 29th of April)

Default

{{reporter}}

johns (username)

557058:5aedf933-2312-40bc-b328-0c21314167f0

Username

{{reporter.name}}

johns

557058:5aedf933-2312-40bc-b328-0c21314167f0

User key

{{reporter.key}}

johns (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}}

John Smith

John Smith

Depending on their usage, existing smart values can be converted in different ways.

Incorrect usage of usernames

Smart values should use the user’s full name, not user names (default value or .name)

These should be changed to:

1 2 3 {{reporter.name}} - INCORRECT: This returns the user's username, not full name {{reporter.displayName}} - CORRECT: renders the user's full name: John Smith {{reporter.displayName.split(" ").first}} - CORRECT: renders the user's first name: John

If you need to uniquely identify the user for an API call, for example, in JQL searches, advanced JSON under More options, or an outgoing webhook, use:

1 {{reporter.accountId}}

Mentions in wiki markup

Mentions in wiki markup should also be converted:

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

Advanced field values (JSON)

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

These values should be converted as follows:

1 2 3 4 5 6 7 // INCORRECT: This will stop working since {{initiator.name}} will no longer return usernames { "fields": { "assignee": { "name": "{{initiator.name}}" } } }
1 2 3 4 5 6 // CORRECT: { "fields": { "assignee": { "id": "{{initiator.accountId}}" } } }

Converting JQL

What will break after 29 April 2019?

Currently, it is possible to search for JQL containing usernames, for example:

1 reporter = johns and assignee in (fred, barney)

After 29 April 2019 these JQL searches will fail and will no longer return valid results. All username's will need to be replaced with their corresponding account IDs.

Converting JQL

Auto-Convert JQL

All stored JQL searches will be auto-converted to the new account ID-based format.

When this occurs, the example above will become:

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

However, you can no longer identify the users in the JQL string. Entering a query like this can also be difficult.

To address this, the following controls can help when entering and reading JQL queries.

Inserting an account Id:
Screenshot of JQL condition when configuring an automation rule. "Insert account ID" and the user dropdown are highlighted.
Resolving users in existing JQL:
Screenshot of a JQL condition for an automation rule. User ID is entered into the JQL field. "Resolve users" is highlighted.

 

Additional Help