Link Mapper module


Incubator (services)






Compatible with Magnolia 6.2.

The Link Mapper module records incoming 404 requests in realtime. Editors can respond to each 404 with either 200 (hide the error), 302, 301 (redirects), or 410 (gone) to tell servers to stop looking for it.

This module is at the INCUBATOR level.

  • Redirects are evaluated after rendering, so pages treated this way will take more time by needing to go through the filter chain twice (About 20-50ms penalty). OTOH, it doesn’t slow anything else no matter how many you have (in difference from virtual URI mappings).

  • You may run into slowness when loading large amounts of data into the JCR from the collection server.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle:

  • Magnolia 6.2

  • Magnolia 6.1

  • Magnolia 5.7



Once installed and configured the link mapper module stores data on a 3rd party server. Data is being collected by the public instance(s) each time a 404 is detected. This data can then be consumed by the author instance (on-demand) in the 404Links app. Editors can examine the data and decide what redirect action (response) should be taken. These redirects can be published to the public instances much the same way virtual URI mappings are done. The difference here is that the virtual URI mappings are handled prior to rendering while the 404 redirects are handled after rendering.


Property Description



To use the link mapper module you will need to obtain a client identifier from Magnolia. This identifier is used to track the data obtained by the filter. This property is set in the module config.



To be able to authenticate at the collection server you need the JWT token which can be found in the console after the startup of the collection server.



The base URL for the 3rd party service collecting the data. Also obtained from Magnolia along with the client identifier.

From version 3.3

Since the rest client is defined as YAML from version 3.3 on it can be set with a decorator.

baseUrl: 'http://localhost:8090/lima/v1/'
Up to version 3.2.2

This property is set on the linkMapperService a node in the rest-client registry.

From the author instance, editors can use the 404Links app to view the data collected on the public instances by the broken links filter. Data is collected from the server using the Reload action. Broken links are displayed along with the corresponding site name and access count. Results can be filtered and sorted in a variety of different ways.

Each entry can be published to the public instances. Use the well known Publish action to trigger the publication. With the Archive Action, it is possible to move the link to the Archive Tab. If the link is accessed further the node will be automatically get unarchived after the next Reload.

The publication of a node is only available after setting the Target and Redirect Type.
There is also an action available from the browser view to quickly blacklist an item.

404app allLinks


The archive list is there to ensure clarity in the main list even with longer use. The same search and filter functions are available. To edit a link, however, it is necessary to unarchive it. If an archived link is accessed again, it is automatically unarchived with the next Reload.

404app archive


The edit dialog offers the possibility to define a redirect type and a redirect target. It is also possible to evaluate a list of referers and query parameters.

Property Description

Link name

Name of the Link shown in the table.



  • Page - Choose a page from the pages app

  • Internal link - Enter an internal link (e.g. /travel)

  • External link - Enter an external link (e.g.

  • Blacklist - Do not redirect to any page. Returns HTTP status code 410 instead. (_Choose this option in combination with the redirect type `410`_)

Redirect type


  • 200: keep URL - Target will be served on the original URI, which may look like a page duplicate.

  • 301: permanent - Use in case the original URI will never exist again (default).

  • 302: temporary - Use in case the original URI will exist again in the future.

  • 410: blacklist - Announce that this page is permanently gone and not likely to ever appear again.

Original Name

Original name from first reload.

Original URI

URL which was causing the 404 error.

When editing an item you can see referrers and query parameters of the request that led to the 404. This is sometimes helpful to fight broken links coming from within the system.
  • 404Link

  • Referrers

  • Query parameters

404Link example

404Link example referrers

404Link example queryParameters

Collection server

The quarkus collection server only works with version >=3.2.2.

The collection server was developed using the Quarkus framework and is available for download from the link below. The server includes a docker file to create a deployable container.

As a database for collecting the information, a PostgreSQL server is needed. The connection to this database can be passed by parameter or configured in the server in the file.


You can clone down the linkmapper postgresql repo:

git clone ssh://


The following parameters can be configured:

Parameter Description


required, default is INFO

The log level of the root category, which is used as the default log level for all categories.


required, default is 8090

The HTTP port.



The PostgreSQL datasource username.



The PostgreSQL datasource password.



The PostgreSQL datasource URL.


required, default is 20

The datasource pool maximum size.


required, default is true

If set to true the server will drop all tables in the datasource and recreate them on server startup.

required, default is false

If set to true the server creates a new public/private key pair for the jwt authentication on server startup. When this happens every token generates before is getting invalid. On the first server startup, a fresh key pair will be generated even if this property is set false.


At every server start, a valid jwt token is generated and written to the server console. Tokens are valid until a new public/private key pair is generated. See Collection server.

For the connection to the collection, server to work a valid token must be entered in the Magnolia backend. See the configuration section above.


Version Notes



Updated for Magnolia 5.7 compatibility.


Initial release of the extension’s version of the module.





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

You are currently perusing through the Link Mapper module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules