How to speed up your Jira and Confluence app migrations to accountID

Reading Time: 3 minutes

We're halfway through the deprecation notice period for Jira Cloud and Confluence Cloud REST APIs to improve user privacy in accordance with the European General Data Protection Regulation (GDPR). This means there are less than 3 months left (deprecation period ends 29 March 2019) to update your apps to use accountID instead of username and/or user key.

If you haven't started or are currently working on updating your app(s) here are a few tips that may help.

Tip #1: Opt-in to the new API behaviors to test your changes

Test your changes by opting-in to the new APIs behaviors before the end of the deprecation period.

To opt-in early, for your cloud app, you will need to update your app descriptor with apiMigrationsset gdpr to true. See example:

  "key": "my-app",
  "name": "My App",
  "apiMigrations": {
      "gdpr": true

For Jira Cloud REST API calls, whether you're making the requests in your app or outside of an app, you will need to add the headerx-atlassian-force-account-id: true, to every request.

For Confluence Cloud REST API calls, whether you're making the requests in your app or outside of an app, you will need to add the query parameter privacyMode=true to any request.

To learn more about the API migration Opt-in see the documentation for Jira Cloud and Confluence Cloud.

Please note that Atlassian may continue to send some personal data fields in certain operations, even if the opt-in mechanisms described above have been implemented.

An example: Some user references in webhook event bodies may still contain usernames.

We are continuing to work through these during the deprecation period. If you have concerns please reach out to us for further information.

Tip #2: Force Jira Cloud change logs to return accountID

After the deprecation period, change logs will no longer include usernames. You can force Jira Cloud to return change logs with accountID instead of username by using the opt in mechanisms described above.

Tip #3: Convert JQL using the Personal Data (PD) Cleaner

After the deprecation period, JQL will no longer accept username or user key as a search clause. To help update your JQL queries, we've introduced a new operation which takes one or more JQL queries with username and/or user keys and converts them to an equivalent JQL query with accountID(s).

Read more about the PD Cleaner here.

The Connect app migration guide for Data Migration has this helpful high-level migration guide:

In order to migrate existing data, apps can use the REST resource /rest/api/2/user/ on the Atlassian application instance (Jira, Confluence, or Bitbucket) to retrieve user details, and update data in their store with the Atlassian account ID of each user. For example, here is a high level migration guide:

  • Alter the data store to add an additional field or column for the Atlassian account ID. These IDs are between 1-128 characters long and contain alphanumeric characters as well as "-" and ":" characters.
  • Create a migration code that loops over all records in the data store that:
    • Identifies a user record by username or email address
    • For each record, makes a request to /rest/api/2/user/ with the relevant data
    • Stores the Atlassian account ID returned in the response into the data store record
  • Alter the data store to remove the username or email address field/column

Recommended: Delete saved usernames and user keys. Only store accountIDs.

We recommend that you delete saved usernames and user keys once you've completed your migration work and only store accountIDs. AccountIDs are safe to store identifiers, while usernames and/or user keys may resemble more direct forms of personally identifiable information.

For your Jira Cloud apps, if you are storing usernames or user keys in your own systems, you can batch find the equivalent accountIDs for those users using a bulk user search. After the deprecation period, user search will no longer accept username or user key.

Tip #5: Reach out if you need help. We are here to help you

If you need help during the migration of your app to use accountIDs please head over to the Developer Community and raise a thread asking for help.

Want to learn more about changes related to privacy? We’ll be holding a Webinar on February 12th to help you during your migration. Register today.