URI mapping

This page and its two subpages describe two URI mapping mechanisms in Magnolia, the URI to repository mapping and the virtual URI mapping.


URI stands for Uniform Resource Identifier, a string of characters which identifies a resource. URI falls into two subsets:

  • Uniform Resource Names (URNs).

  • Uniform Resource Locators (URLs).

The former is a location-independent naming scheme that is used to identify a resource, the latter a means of locating the resource by describing its primary access mechanism. The most common type of locator is a Web address (URL).

For example, urn:isbn:9780199535729 should identify the resource as a 2008 paperback impression of Moby Dick by Herman Melville. In digital form, the text of the Melville’s novel can be located on the internet through the following URLs:

URI mapping in general

URI mapping is a way to redirect an incoming request to a content location which has a different underlying path than the one in the incoming request. Consider the following scenario:

A marketing agency has a system of product marketing campaigns for specific periods of the year. The individual landing pages for product campaigns may reside on the agency’s server under very long paths:


A user-friendly path vs full path

While somebody who visits the website frequently may have no difficulty remembering the long path pattern, it can pose an obstacle for everybody else. The agency may thus decide to offer an alternative routing to the individual campaigns. Instead of releasing the 2017 US campaign for the Model A under the long path gauss-automotive.com/campaigns/us/automotive/gauss/2017/modelA.html, the company decides to roll out the campaign with just gauss-automotive.com/2017modelA.

In this case, the system will need to know that every request arriving in this short form has to be interpreted differently since no campaign page /2017modelA exists in the hierarchy of pages on the server:

Path mapping

A mapping rule will have to be configured for this on the gauss-automotive.com site:

/2017modelA > /campaigns/us/automotive/gauss/2017/modelA.html

URI mapping in Magnolia

In the context of Magnolia there are two types of URI mapping: URI to repository mapping and virtual URI mapping.

URI to repository mapping

URI to repository mapping determines which repository node should be served when a particular URI is requested.

Virtual URI mapping

Virtual URI mapping allows you to create short, convenient URLs that do not match the site hierarchy exactly.

For more details about the mappings, follow the respective links.

Page name conflicts with URI mappings

Sometimes, an editor may give a new page a name that is identical with the value in the configuration of an already existing URI mapping. This could result in hiding the new page from the readers, redirecting each request for the page to a different page. If such a conflict appears, Magnolia will inform the editor about the potential danger by placing a warning icon next to the name of the newly created page:

Page name conflicts with URI mappings warning


DX Core



This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules
6.3 beta

Magnolia 6.3 beta

Magnolia 6.3 is in beta. We are updating docs based on development and feedback. Consider the 6.3 docs currently in a state of progress and not final.

We are working on some 6.3-beta known issues during this phase.