There are two main ways of configuring redirects in Confluence. One is directly from a Confluence page, but this only allows you to configure redirects to that specific page. The other is the main configuration page, which shows you all redirects in the system, as well as some additional settings for administrators.
Prerequisite: Open the app configuration page
There are three ways of reaching the configuration page:
- Navigate to https://yourconfluence/plugins/servlet/vanityurl/admin, substituting "yourconfluence" with your Confluence installation's base URL.
- If you're a Confluence administrator, you can use the "Manage Add-ons" page to click the app's "Configure" button
- Use the in-page dialog to click the configuration page link. This is the primary entry point for users in the link modification group that are not admins, since they do not have access to the "Manage add-ons" screen and are not expected to bookmark the page.
Overview: The App's Main Configuration Page
This is the app's main configuration page:
The configuration page consists of 2 main sections:
- The URL Mappings define, where which short URLs map to. In the above example, the configuration defines that people visiting https://yourconfluence/go/link will be redirected to the internal Confluence page "Welcome to Confluence". It is also possible to define the link to go to an external page, as well as to add an anchor on the target page. You can also set a note for each URL mapping. This section is visible to administrators, as well as members of the link modification user group.
- The Settings section currently contains 2 settings that can only be set by the administrator:
- The Link modification user group is an optional setting with which you can define a Confluence user group that should be able to create and modify URL mapping. This setting can be useful if, for example normal users or certain departments should be able to modify the URL mappings
- With Record access events you can enable access event logging. This means, that every access to shortened URLs is logged in a separate database. In the future, this feature is supposed to enable an analytics-style front-end for the app. For the moment, however, there is no graphical interface for accessing the feature. For now however, you can use the REST API to access the recorded events.
Editing URL Mappings
In order to create URL Mappings (i.e. Redirects / Vanity URLs), e.g. from https://yourconfluence/go/documentation to https://yourconfluence/display/docs/Welcome+to+our+documentation, you need to configure the appropriate mapping:
To create a new mapping, click the Add Entry button, to edit an existing entry, click edit in the row of the entry.
In the resulting dialog, there are 4 fields:
- Shortened URL: Required, this is going to be part of the shortened URL after /go/. Valid symbols are lowercase and uppercase characters, numbers and - . _ ~ ! $ ' ( ) * / . The minimum length is 1 character and they must be unique.
- Long URL: Required, the URL that this mapping is supposed to redirect the users to when they visit the shortened URL. When you activate the checkbox saying that this should be a Confluence page, you can search for Confluence pages.
- Anchor: Optional, the URL fragment that should be attached to the long URL after redirection. This can be useful to direct the user to a heading or section within the page. The target page must have an HTML element with that ID to work, which can be achieved in Confluence by using the anchor macro.
- Note: Optional, a user-defined note. This holds no significance for the app, but could be handy to annotate the mapping.
When you're done, don't forget to click the Save button to save the entry.