External reference factory

The hybrid asset reference factory determines where the content of a hybrid asset will be stored. The reference factory can have one or more "mappings". Each mapping contains a reference template used to create a storage URL pointing to the asset content and a set of voters that decide if the mapping will be used to generate the storage URL.

When an asset is chosen to be transformed into a hybrid asset, the reference factory will find the first matching mapping and generate a storage URL for the asset content. The asset and its new storage URL are passed to an external content store which takes care of transferring the asset’s content to external storage.

Where hybrid asset content resides outside of Magnolia does not have to reflect where it resides within Magnolia, though it can. You can store asset content at different paths in external content stores. You can change the name of the asset content. With voters and the reference template, a reference mapping controls where the content of a hybrid asset will end up.

Reference factory configuration

The reference factory is configured as part of the Hybrid Assets module. The app is configured at Configuration > /modules/hybrid-assets/config/referenceFactory.

Property Description

class

required

Must be info.magnolia.dam.hybrid.mapping.SimpleReferenceFactory.

the reference factory class must implement the interface info.magnolia.dam.hybrid.mapping.ReferenceFactory if you wish to implement your own reference factory.

Reference mappings

Reference mappings are defined at /modules/hybrid-assets/config/referenceFactory/mappings. You can define more than reference mapping.

The reference factory (SimpleReferenceFactory) checks each defined reference mapping in the order they are defined to see if the mapping can be applied to a given asset, the first mapping that can be applied to the asset is used to generate the storage URL for the asset content.

A reference mapping contains the following properties:

Property Description

class

required

Must be info.magnolia.dam.hybrid.mapping.TransformReferenceMapping.

the reference mapping class must implement the interface info.magnolia.dam.hybrid.mapping.ReferenceMapping if you wish to implement your own reference mapping.

referenceTemplate

required

The reference template should produce a unique storage URL or reference understandable by an external content store.

The referenceTemplate can include the following placeholders whose values are substituted into the final storage URL:

  • fileName: the path to the asset without the asset file name

  • baseName: the asset file name minus the file extension

  • extension: the extension from the asset file name

  • nodeId: the JCR node ID of the asset

  • nodePath: the JCR node path

  • nodePathHash: a MD5 hash has of the JCR node path

  • random: a random integer between 0 and 999999

  • timestamp: the current time in milliseconds (UNIX epoch time in milliseconds)

The values of the above will be replaced in the reference template with their current values with placeholders like this: {<placeholder>}.

See below for examples reference templates.

voters

required

A VoterSet (info.magnolia.voting.voters.VoterSet) containing one or more voters. The voters will determine if a reference mapping will be used to generate the storage URL for a given asset.

In addition to standard Magnolia voters, the Hybrid Assets module provides a number of voters, see below.

Example reference templates

One important consideration in a reference template is: will the resulting storage URL be unique? If the storage URL is not unique, you may overwrite hybrid asset content or use the content of a different hybrid asset than intended.

Assets in the Magnolia DAM workspace are uniquely named by their node path or ID, so you can use the nodePath or nodeId placeholders to generate a unique storage URL.

However, if you don’t want replicate the path structure of your asset content on your external storage, you can use the placeholders nodePathHash, random and timestamp to generate a unique storage URL.

  • S3

  • Azure

Example
s3://mgnl-hybrids/{nodePath}

The above referenceTemplate will put the asset content into a bucket named mgnl-hybrids using the asset path. If your asset is located at /foo/bar/myasset.jpg, the resulting URL will be:

Example
s3://mgnl-hybrids/foo/bar/myasset.jpg.
Example
s3://mgnl-hybrids/mgnl-test/${baseName}-${nodeId}-${timestamp}.${extension}

This referenceTemplate will put asset content into a bucket named mgnl-hybrids in the subdirectory mgnl-test. The file name of the content will be <base name of the asset file>-<JCR node ID>-<current time in milliseconds>.<asset file extension>.

If your asset was located at /foo/bar/wisequackingduck.jpg in the DAM workspace, the resulting URL would look something like this:

s3://mgnl-hybrids/mgnl-test/wisequackingduck-f32093ab-b6a4-42da-968d-c2f02144ad69-1580813330904.jpg

The Azure configuration has the following format:

azure://ACCOUNTNAME/CONTAINER/${baseName}-${nodeId}-${timestamp}.${extension}
Example
azure://hybridAccountName/hybridContainer/${baseName}-${nodeId}-${timestamp}.${extension}
Since all assets will be placed in the same bucket and subdirectory, this referenceTemplate uses nodeId and timestamp to guarantee that the storage URL will be unique.

Sample configuration for reference factory and stores

  • AWS S3

  • Azure Blob

referenceFactory:
  class: info.magnolia.dam.hybrid.mapping.SimpleReferenceFactory
  mappings:
    referenceS3:
      class: info.magnolia.dam.hybrid.mapping.TransformReferenceMapping
      referenceTemplate: s3://CONFIGUREBUCKET/${baseName}-${nodeId}-${timestamp}.${extension}
      voters:
        mgnlDam:
          class: info.magnolia.dam.hybrid.voters.NodeWorkspaceVoter
stores:
  storeS3:
    class: info.magnolia.dam.hybrid.store.S3AssetStore
    description: S3 asset store
    enabled: true
accountKey: '/azure-credentials/accountkey' # recommend retrieve these value from Password app for security
sig: '/azure-credentials/sig'
referenceFactory:
  class: info.magnolia.dam.hybrid.mapping.SimpleReferenceFactory
  mappings: !override
    referenceAzure:
      class: info.magnolia.dam.hybrid.mapping.TransformReferenceMapping
      referenceTemplate: azure://ACCOUNTNAME/CONTAINER/${baseName}-${nodeId}-${timestamp}.${extension}
      voters:
        mgnlDam:
          class: info.magnolia.dam.hybrid.voters.NodeWorkspaceVoter
stores: !override
  storeAzure:
    class: info.magnolia.dam.hybrid.store.AzureAssetStore
    description: Azure Blob asset store
    enabled: true
    baseURL: 'blob.core.windows.net'
    endpointSuffix: 'core.windows.net'
    accountName: 'xxxx'
    container: 'xxxx'
    serviceVersion: '2020-10-01'
    signedPermissions: 'racwdl'
    signedStartTime: '2024-04-02T07:18:00Z'
    signedExpiryTime: '2025-01-31T16:18:00Z'
    signedResource: 'c' #you might need to adjust this param base on your required configuration
#    signedResourceTypes: 'sco' #you might need to adjust this param base on your required configuration
#    signedServices: 'bfqt' #you might need to adjust this param base on your required configuration
#    requestParams:
#      param1: 'xxx'
Feedback

Incubators

×

Location

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

You are currently perusing through the Hybrid Assets module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules