The intention behind the API version is to allow vendors the ability to beta test a major revision to their Connect app as a private version, and have a seamless transition for those beta customers (and existing customers) once the major revision is launched.
Vendors can accomplish this by listing a new private version of their app, with a new descriptor hosted at a new URL.
They use the Atlassian Marketplace’s access token facilities to share this version with customers (or for internal use). When this version is ready to be taken live, it can be transitioned from private to public, and all customers will be seamlessly updated.
It’s important to note that this approach allows vendors to create new versions manually, despite the fact that in the common case, the versions are automatically created. This has a few benefits-- for example, it gives vendors the ability to change their descriptor URL if they need to (the descriptor URL will be immutable for existing versions)
This sounds much like what we want to do.
There is one potential catch, however. Not only is our descriptor URL different, the base URL of the new revision is, too. And further up on that documentation page it says:
Once the app is installed in a product, the app’s baseUrl cannot be changed without first uninstalling the app. This is important; choose your baseUrl wisely before making your app public.
My questions:
Is uninstalling the app necessary, even in the scenario outlined above (new descriptor URL, incremented API version, admin approval, …)?
If uninstalling the app is necessary, how will the Confluence instances handle this? (Is there a message in UPM? Will the update just not show? Will it fail silently?)
We can host the next release of the app whoever app-server2 is, put the new version in the marketplace as private, and share that with customers (for private beta) as needed.
Then, during release, we mark it public, and since it represents a new version, the private beta clients simply use the new version already, and everyone else gets upgraded to the new descriptor at the new url.
As far as we can tell, no uninstall necessary, and unless there is a scope change, no admin intervention necessary either.
Is anyone from Atlassian able to confirm that no uninstall is required when changing the baseUrl of the descriptor?
Example: lets say we have https://example.com/atlassian-connect.json as our descriptor URL and we manually create a new version of the app in marketplace and specify a new baseUrl https://example-new.com/atlassian-connect.json and that is the only change (no scope changes etc).
Will customers be required to uninstall and reinstall? Will customers be upgraded automatically or do they have to take a manual step?
I think that the documentation should be changed to provide more clarity on this point.
We have since gone through with the update that occasioned me to ask this question, and, in our case at least, the customers did not have to uninstall the app. The update was completely seamless.
We changed the baseURL on both our Confluence and Jira plugins, that’s over 20k combined installs, it worked fine.
What it might be is if you are stored some authenication state on a server, that becomes invalid, but our plugin is stateless, so we couldn’t confirm that.
The domain where your app is hostedas specifiedin the app descriptor file (atlassian-connect.json) and thebaseUrlvalue can only be changed by removing and reinstalling the app.
If so - that really seems like it’s written by somebody who doesn’t really fully understand how Connect works with the descriptor and the lifecycle. That said - Atlassian might be changing behavior but that would seem like it would require a 6 months deprecation notice since for me that would be changing the current behavior. @nmansilla@rwhitbeck@mpaisley any thoughts?
@danielwester yes, I’m exactly talking about your quote, and especially in connection with the new security requirements, which seem to contradict (?) the way Connect works.
It is not clear to me how the new security requirements forbid changing the baseUrl. The text
The domain where your app is hostedas specifiedin the app descriptor file (atlassian-connect.json) and thebaseUrlvalue can only be changed by removing and reinstalling the app.
Once the app is installed in a product, the app’s baseUrl cannot be changed without first uninstalling the app
That’s not really how it works.
When we do a release (on Jira Cloud or Confluence Cloud), we change the base url from say myapp-server1.mydomain.com to myapp-server2.mydomain.com.
Once I upload the descriptor json to the marketplace, the new version goes out to customers. Unless the new version is requesting new permissions scopes, administrators don’t have to do anything, and customer instances are upgraded automatically.
This means, after the upgrade, customer now still use my plugin, but ay a new base url.
Nowhere in this chain of actions did anyone uninstall the app, and then reinstall it.
This baseUrl string can be changed easily. If you have a look into the repository Bitbucket
...
"baseUrl": "{{localBaseUrl}}",
...
the baseUrl is even treated as a variable. This variable is initiated in the file config.json, which can be set by the developer. No install/uninstall needed (contrary to what the documentation seems to indicate).
Related to that, Bitbucket says it’s the officially supported ACE Node.js framework for Atlassian Connect. When you install it, it installs outdated packages with known security flaws.
Understood. So the documentation is inaccurate. For future reference, I highly recommend using “Give docs feedback” option in the page(https://developer.atlassian.com/cloud/confluence/app-descriptor/). I just went ahead and did that to request an update to the documentation.
I will go ahead and remove the text around the need to uninstall to baseUrl from the Additional requirements PDF as well. This would clear all confusion.
Related to that, Bitbucket says it’s the officially supported ACE Node.js framework for Atlassian Connect. When you install it, it installs outdated packages with known security flaws.
If there are security issues anyone wants to report to Atlassian, please report them here - Bug Bounty: Atlassian - Bugcrowd . That is our external bug bounty program and we reward for legitimate exploitable bugs.
Update October 2024: The information in this thread is no longer correct.
We just had an app update that changed the base URL (preparing for data residency, we switch to subdomains like de.*, us.* to reflect the availability zones). At the same time we switched our backend infrastructure. We had a solid plan on how and when to migrate customer data etc.
But the behavior we saw was nothing like people experienced according to this thread, making our careful plans quite obsolete. So you don’t fall in the same pitfall, here’s what we experienced in October 2024:
We created a new version via the marketplace, pointing to the new descriptor URL with the new base URL. Testing in private, everything worked as expected.
When we tried switching this new private version to public, this triggered a manual app review ticket. It took 8 days for somebody to approve the new app version.
We expected the update to silently roll out. But although this is a minor version update (1.1.16 → 1.1.20), it has to be manually approved by admins in the UPM.
So, changing the base URL of your app, even just the subdomain, is a long process with a lot of gotchas. Switching the base URL between releases, as described by @ademoss in 2019, no longer seems to be viable. (Or did we miss something?)
I’d expect to have a clear documentation about that process from Atlassian. @hari, can you point us to where we can learn about that or put it on Atlassians todo list?
