Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.

Related topics:

This page explains how to use the delivery endpoint so that it resolves references to nodes from different workspaces.

The information on this page only applies to delivery endpoint API v2. If you want to resolve references with version 1, see Delivery endpoint API v1 - reference resolving configuration.

What is reference resolving?

The endpoints of the delivery API are configured to return content as JSON from one JCR workspace (configured with the workspace property). 

Here is a JSON response of a tour from the workspace tours.

{
  "@name": "Kyoto",
  "@path": "/magnolia-travels/Kyoto",
  "@id": "b475f27e-2929-427b-9517-815118a3b36e",
  "@nodeType": "mgnl:content",
  "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We&#39;ll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You&rsquo;ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You&rsquo;ll never think about Japan in the same way again.</p> ",
  "name": "Kyoto",
  "description": "The natural side of Japan",
  "destination": [
    "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
  ],
  "location": "Kyoto, Japan",
  "tourTypes": [
    "d2245867-ecaa-4b4e-8743-e0c939be68b7",
    "415025c6-e4b5-4506-9384-34f428a52104"
  ],
  "author": "Magnolia Travels",
  "duration": "7",
  "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
  "@nodes": []
}
  • Lines 13-15: The tourTypes property contains two references to tour type nodes that reside in the category workspace.

  • Line 19: The image property contains the asset identifier, which is the reference to an asset. In this case the asset is stored in the Magnolia DAM in the dam workspace. In other cases, the asset could be in another asset provider.

We could send additional requests to deliver content for the category and dam workspaces. However, it is more efficient to get the data of the referenced nodes directly with the first request by resolving the references.

In the following sections, we show you how to configure the delivery endpoint in order to resolve the references. 

Details concerning the example:

The JSON is requested with this URL: http://localhost:8080/magnoliaAuthor/.rest/tours/magnolia-travels/Kyoto

The basic configuration for the delivery endpoint to read tours in the example so far is:

restEndpoint/tours.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: tours
includeSystemProperties: false
#references

The references and the referenceResolver properties

The references property is used in both  (for delivery endpoint API v1) and  (for the delivery endpoint API v2). On this page we focus on v2.

Configuration example:

references:
  - name: tourTypeReference
    propertyName: tourTypes
    referenceResolver:
      class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
      targetWorkspace: category

Properties

references

The references node contains a list of reference definitions. The properties of a single reference are defined in .

name

optional

An arbitrary name. If you do not set the property, the first property must start with a - in order to have proper YAML list item. Using the name property improves the readability of the YAML file.

propertyName

required

The value of this property contains the name of the JCR node property that stores one or multiple references to nodes of other workspaces.

nodeType

optional

The value must be a valid node type. If set, references are resolved only on nodes of the given type.

referenceResolver

required

The reference resolver defines how references are resolved, the properties are defined in .

class

required

The value must refer to a class or interface extending .

Reference resolver definition classes provided by Magnolia:

  • info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
  • info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition

Note that these classes may have further properties that must be configured.

Resolving jcr node references

Magnolia provides a JCR node reference resolver that is suitable in most cases, with the exception of assets. Use the definition class  for configuration.

Example configuration

This example is based on the basic configuration shown above.

restEndpoint/tours.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: tours
includeSystemProperties: false
references:
  - name: tourTypeReference
    propertyName: tourTypes
    referenceResolver:
      class: info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition
      targetWorkspace: category
      expand: true
      generateLink: true

The lines 5-11 define how the references stored in the field tourTypes are resolved.

{
  "@name": "Kyoto",
  "@path": "/magnolia-travels/Kyoto",
  "@id": "b475f27e-2929-427b-9517-815118a3b36e",
  "@nodeType": "mgnl:content",
  "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We&#39;ll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You&rsquo;ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You&rsquo;ll never think about Japan in the same way again.</p> ",
  "name": "Kyoto",
  "description": "The natural side of Japan",
  "destination": [
    "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
  ],
  "location": "Kyoto, Japan",
  "tourTypes": [
    {
      "@name": "ecotourism",
      "@path": "/tour-types/ecotourism",
      "@id": "d2245867-ecaa-4b4e-8743-e0c939be68b7",
      "@nodeType": "mgnl:category",
      "body_de": "Die Natur ruft Sie. Und es gibt nichts natürlicheres als die afrikanische Savanne oder die eisige Wildnis der Antarktis. Aber was noch besser ist, als der Natur nahe zu sein, ist das Wissen, dass Sie dazu beitragen, diese unberührten Flecken der Erde so zu belassen, wie sie sind, wenn Sie mit uns reisen. ",
      "body": "Nature is calling you. And there’s nowhere more natural than Africa’s savannah plains or the icy wilderness of Antartica. But what’s even better than getting closer to nature is knowing that when you travel with us, you’re making your own contribution to keeping those untouched parts of earth just as they are.",
      "description_de": "Der Ruf der Wildnis",
      "name": "ecotourism",
      "level": "level-1",
      "description": "Call of the wild",
      "displayName_de": "Ökotourismus, Pflanzen- und Tierwelt",
      "icon": "jcr:8ad908e7-2ab7-4fe2-b1ed-e6eb3f68f3b0",
      "displayName": "Ecotourism, Nature & Wildlife",
      "image": "jcr:2fd89d97-f932-4533-8a30-d70988bde30c",
      "@link": "/magnoliaAuthor/tour-types/ecotourism.html",
      "@nodes": []
    },
    {
      "@name": "offPath",
      "@path": "/tour-types/offPath",
      "@id": "415025c6-e4b5-4506-9384-34f428a52104",
      "@nodeType": "mgnl:category",
      "body_de": "Auf einem großen Reisebus sitzen, Touristengerichte essen und Fotos vom Eiffelturm machen ist nicht Ihre Vorstellung vom Reisen. Sie möchten etwas Neues finden und die Dinge aus dem örtlichen Blickwinkel betrachten. Mit uns können Sie die örtlichen Juwelen entdecken, die die meisten Reisenden nie sehen. ",
      "body": "Riding on a big tour bus, eating tourist menus and taking pictures of the Eiffel Tower is not your idea of travelling. You want to find something new, and see things from a local point of view. With us, you can discover the local gems that most travellers never experience. ",
      "description_de": "Einzigartige Ferien abseits der ausgetretenen Pfade",
      "name": "offPath",
      "level": "level-1",
      "description": "Unique holidays that take you off the beaten track ",
      "displayName_de": "Abseits der Trampelpfade",
      "icon": "jcr:6d5d576a-79f9-48d9-b141-6682f2eef585",
      "displayName": "Off the Beaten Path",
      "image": "jcr:272f75b9-ed87-4e0b-8bf3-15db217ba897",
      "@link": "/magnoliaAuthor/tour-types/offPath.html",
      "@nodes": []
    }
  ],
  "author": "Magnolia Travels",
  "duration": "7",
  "image": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
  "@nodes": []
}

Properties

class

required

Must be info.magnolia.rest.reference.jcr.JcrReferenceResolverDefinition or a subclass.

targetWorkspace

required

The name of the workspace containing the nodes that are referenced.

expand

optional, default is true

If set to true, all properties of the referenced node are included in the JSON.

If false, the JSON contains only links to the referenced node. See generateLink below.

generateLink

optional, default is false

If true, the resolved node contains an additional link property. The value of the link property is a relative link to directly render the referenced node.

The format of the generated links depends on the configuration of the link generator (configured in config workspace at /server/rendering/linkManagement).

Resolving asset references

Magnolia REST modules come with an asset resolver, which creates a (relative) link to the image as well as Dublin Core metadata (if it exists for the asset). Use the definition class  for configuration.

The Magnolia asset resolver operates on the DAM API - this ensures it can resolve assets from any asset provider such as Cumulus DAM connector or Amazon S3 Connector.

If the referenced assets reside in the Magnolia DAM, the asset resolver can also generate links to asset renditions (also known as image variations). Renditions must be defined in the theme that is linked to the site definition. See image variations to learn how to define asset renditions in a theme.

For image variations to be resolved correctly, make sure that the fallback site has theme variations configured or extends a site definition with desired variations.

Example configuration

This example is based on the basic configuration shown above.

restEndpoint/tours.yaml
class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: tours
includeSystemProperties: false

references:
  - name: tourImageReference
    propertyName: image
    referenceResolver:
      class: info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition
      assetRenditions:
        - 320x240
        - 1600x1200
        - nonexistent

The lines 5-11 define how the references stored in the dam workspace are resolved. 

{
  "@name": "Kyoto",
  "@path": "/magnolia-travels/Kyoto",
  "@id": "b475f27e-2929-427b-9517-815118a3b36e",
  "@nodeType": "mgnl:content",
  "body": "<p>Experience the still beauty that permeates and surrounds Kyoto. Kyoto is famous for many things, including countless <a href=\"http://www.japan-guide.com/e/e2058.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>temples</u></a>, <a href=\"http://www.japan-guide.com/e/e2059.html\" style=\"text-decoration:none;\" target=\"_blank\"><u>shrines</u></a> and other fascinating historical buildings.</p>\n<p>Join us on a visit to the City of Ten Thousand Shrines. We&#39;ll visit Tō-ji, Ginkaku-ji, Kōzan-ji and their remarkable gardens before venturing into the mountains that surround the city. You&rsquo;ll enjoy a day spent in green Miyama and a day hiking in Shizuhara. You&rsquo;ll never think about Japan in the same way again.</p> ",
  "name": "Kyoto",
  "description": "The natural side of Japan",
  "destination": [
    "7ec72c48-c33f-418e-b2ff-44cfb4bbb1f2"
  ],
  "location": "Kyoto, Japan",
  "tourTypes": [
    "d2245867-ecaa-4b4e-8743-e0c939be68b7",
    "415025c6-e4b5-4506-9384-34f428a52104"
  ],
  "author": "Magnolia Travels",
  "duration": "7",
  "image": {
    "@name": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
    "@path": "/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
    "@id": "jcr:44689d29-5966-4d41-8fd4-2dc7da783528",
    "@link": "/magnoliaAuthor/dam/jcr:44689d29-5966-4d41-8fd4-2dc7da783528/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
    "metadata": {
      "fileName": "flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg",
      "mimeType": "image/jpeg",
      "caption": "Tasteful Tn",
      "fileSize": "1115288",
      "height": "2133",
      "width": "1600",
      "format": "image/jpeg",
      "rights": "by-sa/2.0",
      "creator": [
        "superuser"
      ],
      "date": "2015-06-03T14:32:30.249+07:00",
      "created": "2015-01-29T14:45:41.613+07:00",
      "modified": "2015-06-03T14:32:30.249+07:00"
    },
    "renditions": {
      "320x240": {
        "mimeType": "image/jpeg",
        "link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/320x240/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
      },
      "1600x1200": {
        "mimeType": "image/jpeg",
        "link": "/magnoliaAuthor/.imaging/mte/travel-demo-theme/1600x1200/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg"
      },
      "nonexistent": {
        "mimeType": "image/jpeg",
        "link": "/magnoliaAuthor/.imaging/default/dam/tours/flickr-japan-gate-tasteful_tn-204886404_ab34d73333_o.jpg/jcr:content.jpg"
      }
    }
  },
  "@nodes": []
}

Note:

  • Line 23: The property @link provides a relative link to the asset. The asset is served by the .
  • Line 40 pp - renditions. When requesting the links of the renditions, they are served by the .
    • Line 43: The link contains a relative link to an asset rendition (of a defined image variation).
    • Line 51: The link to an undefined rendition returns the original uploaded asset. Here it returns as @link of line 40 (the former served by dam servlet, the latter served by imaging servlet).

Properties

class

required

Must be info.magnolia.rest.reference.dam.AssetReferenceResolverDefinition or a subclass.

expand

optional , default is true

If set to false, neither the list of defined renditions nor the meta data is shown.

If includeDownloadLink is set to true, a link is returned, otherwise the asset item key or original text is shown.

includeDownloadLink

optional, default is true

If set to false, the JSON file does not show the relative asset link.

includeAssetMetadata

optional, default is true

If set to false, metadata is not included.

assetRenditions

optional

A list of rendition names as defined in the theme linked to the current site.

<rendition-name>

required

The rendition name.

If you add an undefined – and therefore non-existent rendition – the asset resolver creates a link to the default variation which is the same as the asset in its original size.




6 Comments

  1. Christoph Meier

    Christoph Meier - Resolving asset references works also for assets residing  on Amazon S3 Connector module.

    Here is a gist from Alberto, which works fine.

    Add a note to this page and on DOCS60.

  2. Marvin Kerkhoff

    Hi, is there a way to get nested references resolved? For example a DAM asset inside a referenced object?

  3. Christoph Meier

    tbh - I have never tried this.

    But good idea ... I should  try this out ...

  4. Loukas Andreadelis

    Christoph Meier Have you given nested references resolution a try or it's only possible with custom Java endpoints?

    1. Christoph Meier

      Hi Loukas

      I haven't tried it out. Sorry.

  5. Loukas Andreadelis

    Hi Christoph

    All my tests to existing api haven't managed to get nested reference resolution. It's only for root level.

    Looks like it's not feasible, only solution is custom.