Purpose
The Workzone app needs to add a new scope for example ‘project:admin’ to be able to read project permissions. Unfortunately there is no way to update the app descriptor for an app installed from the Atlassian Marketplace into Bitbucket Cloud. To update Workzone to the latest version and accept the new scope, the following steps are required for each Workspace where Workzone has been installed:
- Export all Workzone data through the new export/import feature in Workspace settings into a JSON file.
- Uninstall the Workzone app
- Reinstall the Workzone app
- Acknowledge app scopes
- Import all Workzone data in the Workspace settings and re-approve app scope permissions.
Currently, Bitbucket Cloud has no way of updating the descriptor in the Workspace admin section of Bitbucket if Workzone has been installed via the Atlassian Marketplace. We have talked to the Atlassian Bitbucket team, who suggested to enable “development mode” in Workspace Settings > Installed apps settings. Here are the differences between ‘development mode’ and non-development mode.
| Non development mode (via Marketplace) | Development mode (via URL) | |
|---|---|---|
| Workzone installation | Via UI from Workspace settings > Marketplace > Workzone | Via URL from Workspace settings > Installed Apps > Descriptor URL: https://workzonecloud.net/atlassian-connect.json |
| App scopes acknowledgement | Via UI dialogue | Via UI dialogue |
| Workzone app descriptor updates – no scope change | Automatically | Automatically |
| Workzone app descriptor updates – with scope change | Export settings Uninstall appReinstall app Acknowledge app scopes Import settings | Update app via Workspace settings > Installed apps > Workzone > Update button Acknowledge app scopes |
| Future app scope changes | Export, re-install, import required Acknowledge app scopes | Update button Acknowledge app scopes |
Impact
Workzone will be unavailable while you re-install the app. All settings are restored after re-importing settings.
Please reach out to our support team here if you are undecided or need further assistance on how to go forward with the upgrade.
Export Process
- Navigate to your Workspace Settings from the top right settings icon.
- Click on “App Settings” under the “Workzone” title.
- Under the “Export and Import Workzone Data” section, click on “Export Data”
- This will open a popup and begin exporting all Workzone data into a json file. Once the progress bar has been completed, the json file will be downloaded.
- If you are exporting Workzone data to uninstall & reinstall Workzone, you can now install Workzone. If you are exporting data for backup purposes, you can now safely store the json file.
Uninstall the Workzone App
- Navigate to your Workspace Settings from the top right settings icon.
- Under “Apps and features” click on the “Installed Apps” button.
- Click on the Workzone app dropdown.
- Click the “Remove” button. Then the “remove” button again in the popup.
- A popup will appear confirming the Workzone app has been uninstalled.
Reinstalling the Workzone App
- Navigate to your Workspace Settings from the top right settings icon.
- Click on the “Marketplace” button under Apps and Features.
- Scroll down and find the “Workzone: Pull request workflow” app. Click “Add”
- Click “Grant Access”
- The new descriptor will now be installed.
Import Process
- To begin the import process: Navigate to your Workspace Settings from the top right settings icon.
- Click on “App Settings” under the “Workzone” title.
- Under the “Export and Import Workzone Data” section, click on “Import Data”
- Select the Workzone Export json file you want to import, then click “Confirm”
- You should now see a confirmation popup in the bottom left of your screen instructing you to reload the page. The data on the current page will not reflect the new import until you reload the page.
If you do not see this confirmation popup, please contact support.