Back to the blog
  • Mar 29, 2022
  • --
Category Tech
Virtual URI Mapping 1200x628
Headless Magnolia: Mapping Virtual URIs

Headless Magnolia: Mapping Virtual URIs

If you want to learn about Magnolia’s take on headless content management but don't know where to start, you've come to the right place. As part of our “Headless Magnolia” series, we’ll break down relevant features that allow you to use Magnolia as a headless CMS.

In this article, we will look at how to redirect an incoming request to a target destination, also known as virtual URI mapping, for example:

From: /ilm

To: /product/i_love/magnolia

Where to Use Virtual URI Mappings

Virtual URIs are commonly used in marketing to shorten the length of a URL, for example, for:

  • Microsites

  • Landing pages

  • Product pages

  • Campaign and conversion pages

  • Downloads

  • Events and conferences

  • Vanity URLs

Other reasons for redirecting URLs are related to day-to-day site maintenance, such as:

1. A page has moved due to site re-organization. However, users still have the old URL bookmarked and so do search engine indexes. Without redirection, traffic to your old page location would be lost.

2. If you own several domain extensions like and, you probably want to redirect these to your primary website You can map multiple domain names to a site in your Magnolia site definition. This can be a major time-saver for a CMS team since there is no need to configure a web server.

Note that you need to register the domains with a registrar first and make sure that the DNS entries for the domains point to the server hosting your Magnolia instance.

Finally, you can use URI mappings to turn a template-based JSON provider into a RESTful API, for example, an FTP Magnolia page that returns JSON:

Original path: /getjson/tours/magnolia-travels/Kyoto

Target path: /getjson?workspace=tours&path=/magnolia-travels/Kyoto

Headless Magnolia: Building a Basic SPA Using Magnolia Templates

In this article of our Headless Magnolia series, we'll create a basic Singe Page Application (SPA) that you can edit in the Magnolia Pages App.


You can create virtual URI mappings by creating a YAML configuration file in the virtualUriMappings folder in your module’s configuration. Every URI mapping requires a separate file.

Please note that the folder name must be plural and use camel case for “URI”, making it “Uri”.

File: <my-module>/virtualUriMappings/enterprise-edition.yaml

  class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: /ilm
toUri: forward:/product/i_love/magnolia

The properties are:

  • class: The class that performs the mapping. Check the section on mapping classes below.

  • fromUri: The pattern to match in the requested URI.

  • toUri: The URI that the request shall be mapped to with an action prefix name.

  • site: Required for the MultiSiteRegexpVirtualUriMapping class to specify the site that should be used for the mapping.

Mapping Classes and Actions Prefixes

Magnolia provides a number of classes that perform virtual URI mapping.

These are the most commonly used ones:

  • info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping maps a virtual URI to a content path. This is the simplest and most common type.

  • info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping allows you to specify a regular expression pattern that matches a sequence of characters. A regexp pattern can match a variety of URIs, which saves time and effort as you would otherwise have to create default mappings for each. toUri can contain back-references to the regexp matches.

  • info.magnolia.multisite.mapping.MultiSiteRootVirtualUriMapping is a special class that specifies the root of a site if site matching returns null.

  • info.magnolia.multisite.mapping.MultiSiteRegexpVirtualUriMapping adds a site condition to the URI check. A mapping will only match the request if both the specified regular expression and the specified site match.

In toUri you can use these action prefixes:

  • forward hides the target URL from the visitor. The URL that the user typed in the browser address bar or the link they clicked does not change for them.

  • redirect returns the HTTP response status code “302 Found” to the client. While this is ok for human visitors, this method is not ideal for search engine optimization (SEO) as search engines do not transfer the page rank of the old URL to the new URL when receiving this code.

  • permanent is a search-engine-friendly redirect option. It returns the HTTP response status code “301 Moved Permanently” and preserves your search engine ranking for the redirected page.

  • proxy forwards the original URL to an external URL.


  class: info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping
fromUri: ^/static/(.*)
toUri: redirect:$1
  class: info.magnolia.virtualuri.mapping.RegexpVirtualUriMapping
fromURI: ^/profile/(.*)/(.*)$
toURI: forward:/people-profile-page
  class: info.magnolia.virtualuri.mapping.DefaultVirtualUriMapping
fromUri: /foo
toUri: forward:/bar
  class: info.magnolia.virtualuri.mapping.MultiSiteRootVirtualUriMapping
site: site-one
fromUri: /lorem
toUri: redirect:

Learn more about Magnolia’s headless features

This Headless Magnolia series will cover the following topics:

About the Author

Bartosz Staryga Front-End Solution Architect at Magnolia

Bartosz is an expert in headless content management and front-end development at Magnolia. He designs and develops new Magnolia features and supports customers with their headless implementations from content types to APIs to integrations. Bartosz enjoys building new things and seeing them in action. He is also a trainer for Magnolia’s Headless training.

Read more