Wiki source code of Setup Confluence URL Mapping
Last modified by Vincent Massol on 2026/04/08 13:50
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{warning}} | ||
| 2 | We assume you run your XWiki instance behind a reverse proxy you control. If you don't, it will probably be hard to use Confluence URL Mapping in practice). | ||
| 3 | {{/warning}} | ||
| 4 | |||
| 5 | = How to setup = | ||
| 6 | |||
| 7 | == Define a URL prefix == | ||
| 8 | |||
| 9 | First, define a URL prefix that will receive requests with old confluence urls. For technical reasons, **this prefix must be an alphanumerical string without slashes and dashes.** | ||
| 10 | |||
| 11 | Assuming your wiki is reachable at ##https:~/~/example.com/xwiki## Old Confluence URL will work at: | ||
| 12 | |||
| 13 | {{code language="none"}} | ||
| 14 | https://example.com/xwiki/CHOOSENPREFIX/ | ||
| 15 | {{/code}} | ||
| 16 | |||
| 17 | In the reminder of this documentation, we will assume the ##oldwiki## prefix. Handled URLs will look like: | ||
| 18 | |||
| 19 | {{code language="none"}} | ||
| 20 | https://example.com/xwiki/oldwiki/pages/viewpage.action?pageId=163919355 | ||
| 21 | https://example.com/xwiki/oldwiki/display/CONF719/Customize+your+Space | ||
| 22 | {{/code}} | ||
| 23 | |||
| 24 | == Install the Confluence URL Mapping extension on XWiki == | ||
| 25 | |||
| 26 | 1. Install the Confluence URL Mapping extension in your main wiki. | ||
| 27 | 1. Make sure the URL Mapping extension was also installed. It should be, but if it isn't, install it | ||
| 28 | |||
| 29 | == Configure Confluence URL Mapping == | ||
| 30 | |||
| 31 | in xwiki.properties, put: | ||
| 32 | |||
| 33 | {{code language="none"}} | ||
| 34 | urlmapping.prefixhandlers.confluence.prefix=oldwiki | ||
| 35 | {{/code}} | ||
| 36 | |||
| 37 | (Replace oldwiki to whatever prefix you want to use) | ||
| 38 | |||
| 39 | See [[the documentation of the URL Mapping module>>doc:documentation.extensions.admin.url-mapping.URL-Mapping-configuration.WebHome||anchor="HConfiguration"]] for all the parameters you can use. The configuration name to use for the Confluence handler is ##confluence##. | ||
| 40 | |||
| 41 | By default, there's no delay and old URLs are transparently redirected to the new URLs, but you can, for instance, specify a delay and a custom message to let your users know they used an old URL and that they should update their bookmarks. | ||
| 42 | |||
| 43 | == Configure your reverse proxy == | ||
| 44 | |||
| 45 | You will need to configure your reverse proxy to route old Confluence URLs (likely ##/wiki/...##) to ##/xwiki/oldwiki/...##. Of course, if your Confluence wiki was hosted at another domain name than XWiki, you will need to handle this old domain and redirect to the new domain as well. | ||
| 46 | |||
| 47 | For the reverse proxy routing, you can use redirects, or proxy directives to avoid the extra redirects. |
