Dynamic Catalogs

Dynamic catalogs allow end-users to override the catalog mappings by dropping specific catalog files into a folder and have these files automatically loaded into the system. Dynamic catalogs can be updated with a dedicated API, and can be used with LinkManager or through publication pipelines.

Name of the dynamic catalog

The default name for such catalogs is catalog.xml. This name can be changed through the componize.catalog.autoload.filename system property, for example in alfresco-global.properties).

# file name for the auto-loading catalogs

URI resolution

By defaut, in any directory, when some URI gets resolved (e.g. to resolve a link, or in a pipeline execution), extra catalogs will be loaded and take precedence over the default (static) catalogs. "Take precedence" here means that if there are duplicate entries in dynamic and static catalogs, the one from the dynamic catalog will be the one that gets applied. But dynamic catalog are provided in addition to the static ones. This means that if there is no mapping for a given URI in any dynamic catalog, the static catalogs still apply.

For example from this resource point of view: alfresco:/path/to/folder/file.xml, when resolving an href attribute from this file.xml, Componize will try and apply these catalogs (if they exist) in addition to the static ones that were loaded during startup:
  • alfresco:/path/to/folder/catalog.xml
  • alfresco:/path/to/catalog.xml
  • alfresco:/path/catalog.xml
  • alfresco:/catalog.xml
Note: There is a cache in effect at the catalog service level to speed things up. An Alfresco behavior ensures that if any of these catalogs is updated manually, the cache gets emptied.

Dynamic catalogs API

Componize provides an API to update dynamic catalogs. Using the API has the the following benefits:
  • The cache is updated automatically
  • Using the API is easier than writing your own catalogs.
Note: The dynamic catalogs API is part of Componize public API. The main interface is CatalogService.

Updating the mappings at any given base URI

Important: The baseUri is basically a folder where catalog.xml is stored. Add a final / for the base URI.


LinkManager allows to use dynamic catalogs. When links are extracted they are resolved through catalogs. But to prevent any inconsistency, links are not "connected" if they were resolved through a catalog. Adding a mapping to replace a given href in a document to some other resource implies the link is assumed to be like an "external" one, so that when the target document is moved or renamed, the source document is not rewritten.
Note: Reverse lookup in a catalog cannot be performed for now.