RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
This new initiative will help address one of the most requested features in Confluence: allowing users to rename space keys. This will solve the problem of conflicting spaces during migrations.
- Publish: June 7, 2024 (PST)
- Discuss: June 20, 2024 (PST)
- Resolve: June 28, 2024 (PST)
Problem:
The ability to change a Space key has garnered significant interest from numerous customers. Customers frequently request the capability to rename space keys due to organizational changes such as modifications in team or project names, acquisitions by other companies, organizational restructuring, or alterations in user names. Furthermore, it creates obstacles when attempting to migrate spaces between Confluence instances with identical space keys.
Proposed Solution:
Since the beginning, the Space key has been used as a unique and immutable field by our app developers. As part of the proposed solution, we are going to keep the existing Space key as it is.
What is being introduced is a Space Alias. This is can be created and applied to a Space after the creation of a Space. The Space Alias will be what is presented about a Space. So, in a URL where there was a Space key there will be a Space Alias. For example:
Existing URL: https://example.atlassian.net/wiki/spaces/SPACEKEY/settings/home
New Changed URL: https://example.atlassian.net/wiki/spaces/SPACEALIAS/settings/home
What is changing is that the field in the URL that is currently populated by the Space key will become a Space alias.
After a transition period, the provided Space key will be stored as a Space Alias and the Space Key will be an internally generated ID. No existing Space keys will be changed.
In addition, any stored URLs with a Space key or Space Alias will continue to work even if a new Space Alias is applied to a Space.
API Support:
All the APIs that are compatible with the space key will also be compatible with the space alias.
For instance, the Get Spaces (v2) API will accept an alias in the keys query parameters.
Key field in API Response
The key field in the API response will remain unchanged, consistently containing the actual space key (Internally generated id moving forward) for the specified space.
Existing Space Key
There will be no changes to the existing space keys. All current space keys will still utilize the UGC space key. Only spaces created after this launch will receive an internally generated ID.
No changes in AP.context.getContext()
The space key retrieved through the AP context remains unchanged. It will consistently return the actual space key in the response. The alias will be a new field that returns the new Space Alias. In the case where no Space Alias has been set, the Space Alias will be the same as the Space key.
AP.context.getContext()
{
"confluence": {
"space": {
"key": "SPACEKEY",
"id": "SPACEID",
"alias": "SPACEALIAS" // New field coming as part of EAP
},
"content": {
"plugin": "pluginKey",
"type": "TYPE"
}
},
"url": {
"displayUrl": "https://example.atlassian.net/wiki"
}
}
Supports URL redirect with older alias.
Links with previous space keys or aliases will be automatically redirected to the currently active alias. All APIs that require a space key will also support this functionality, ensuring that appropriate spaces are provided in response to older aliases.
The upcoming changes to the APIs as detailed below
- V1
Create SpaceandCreate Private SpaceAPIs- The space key will now be an internally generated ID. We are going to deprecate the space key field in the above two APIs, and it will be marked as optional during the deprecation notice. During the deprecation period, if the space key is included in the request, the space will be created with the given space key.
- A new field,
alias, will be added. This will be used to create a space with the given alias. (This is an optional field during the deprecation period.) - The key field in the request is scheduled to be deprecated during the first week of January 2025. Following deprecation, the key provided in the create space request will be ignored.
- V2
Get SpacesandGet Space By IdAPIs- A new field,
alias, will be added to the response.
- A new field,
Asks
We kindly request that the developer refrain from scanning URLs to parse space keys. If this is currently being done, we strongly recommend transitioning to AP.context.getContext() or utilizing our V2 Space API to obtain the correct space key from its response.
The Alias field is subject to change, so it is recommended to avoid using aliases to store your application data. Instead, opt for using the Space ID whenever feasible.
The initial release is scheduled for the end of June for developer EAP. This feature will be activated exclusively for developer sites, allowing you to test your apps against the change to ensure proper functionality. In the meantime, if your app is parsing the URL for space key, please make the necessary adjustments as outlined above.
If you are interested in registering your site for the developer EAP, Please follow the steps as described here
Thank you in advance for your collaboration and support in shaping the future of the Confluence
