Page Comparison

...

The syntax of the URL is: dfsmedia/[SiloId]/[AssetId]-[Quality]/resize/[Width]x[Height]/cropsize/[Width or ratioX]x[Height or ratioY]/cropmode/[Mode]/cropposition/[Position]/outputimageformat/[Format]/compress/[0-100]/options/[Options]

...

dfsmedia/[SiloId]/[AssetId]-[Quality]/compress/[0-100]

Info
Each

...

Field

...

Description

...

SiloId

...

This is the Id of the silo that has the asset requested.

...

AssetId

...

Is the Id of the asset that is requested.

...

Quality

...

Overrides the quality specified in the Sitecore field.

Quality supports both 'by name' and 'by id'

...

Resize

*

Only applies to image assets.

...

of the parameters must be en the correct case. For example the resize paramater must not be like this Resize, only lowercase.

Info
Before you can use the resizing and cropping feature, the sync user from this section DFS 11.1 - 3 Setting up Sitecore, must have the Digizuite role `Asset_Can_Download_Custom_Quality`.

Each parameter is described as follows:

Field	Description
SiloId	This is the Id of the silo that has the asset requested.
AssetId	Is the Id of the asset that is requested.
Quality	Overrides the quality specified in the Sitecore field. Quality supports both 'by name' and 'by id'
resize *	Only applies to image assets. One of the concepts and principles when using a DAM system is to use specific qualities for every use. If images are needed in different sizes, it should be configured in Digizuite™ DAM. However, there is a resize feature. Width How wide the image will be in pixels. Height How high the image will be in pixels. By default a resize does not keep aspect ratio, but you can set an option to keep aspect ratio.
Compresscropsize *	Only applies to image assets. Indicates whether the asset should be saved using a worse quality, thereby reducing the physical size. from 0-100 is allowed, where 0 is the worst quality, but least physical storage.
Options *	Options is a dash ("-") separate list and can contain these options: download - Will download the asset requested. keepaspectratio - Will enforce aspect ratio on from the original asset, if a resize is requested. boxfit - If a resize ia requested and you supplyed both the width and heigth. The resized image will not exceed these values and still keep the aspectratio. upscaleallowed - Will allow upscaling an image. The default is to disallow that.

*Optional

Understanding the DigizuiteMediaCache

The DigizuiteMediaCache is where everything, except videos, is saved. The cache location is configurable and is located in DFS.Settings.config

DFS.Settings.config

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <settings>
	  <!-- Path to DAM For Sitecore MediaCache. The following is supported: 
             -UNC (\\server\example\cahcepath)
             -Full path (C:\example\cachepath)
             -Relative path (/App_Data/cachepath)      
      -->
      <setting name="DFS.CacheLocation" value="/App_Data/DigizuiteMediaCache"/>
	</settings>
  </sitecore>
</configuration>

The default location is in the website root under App_Data/DigizuiteMediaCache/.

Files are cached based on the request made to the asset. An example request could be: http(s)://<sitecore url>/dfsmedia/29a605d46a3340418c16542f7272c3ec/110-50035

According to the specification of the URL, this request has the following properties:

AssetSiloId: 29a605d46a3340418c16542f7272c3ec
AssetId: 110
FormatId: 50035

The cache is then build using a naming scheme. Each asset is placed in a sub-folder which has the name of the assetid. In the case of the example, the path in which the file is saved would be App_Data/DigizuiteMediaCache/110

The filename is then constructed based on the given properties using the following scheme:

{Assetid}_{formatid}_{width}_{height}_{options}.{extension}

where width, height and options are not used, if not requested (i.e. not used in the example), which means in the example, the requested asset would have the following name:

110_50035.{extension}

The extension is retrieved from the file saved in the cache. The naming scheme enable unique names and hence the extension can be extracted from the file in the cache. Originally, the file is saved with the correct extension based on what is served from the Digizuite.

UNC path

The dfsmedia pipeline also supports having a centralized cache, which means multiple servers can have the same cache. This decreases storage, but also performance, because files are then cached on a UNC which is slower than having it locally. This is something each client has to have an opinion on.

Implementation

The new dfsmedia pipeline is implemented as a httphandler, using a pipeline in Sitecore. This pipeline is located in the DFS.Pipelines.config file:

DFS.Settings.config

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
	<pipelines>     
	 <DFS.Services.DFSMedia>      
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset, DFS.Client.Services" role:require="Standalone or ContentManagement" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuite, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SaveToCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename, DFS.Client.Services" />
      </DFS.Services.DFSMedia>
    </pipelines>
  </sitecore>
</configuration>

Each step is explained as follows:

Pipeline name	Description
DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset	This is only running in role:require="Standalone or ContentManagement". Will sync the asset into the asset silo if it does not exist.
DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity	Looks up the asset item.
DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache	This pipelines constructs a unique name based on the request and checks if the requested asset exists in the cache.
DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage	If resize is requested, the image will be resized.
DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuite	This pipeline executes the request towards Digizuite
DFS.Client.Services.Pipelines.DFSMedia.SaveToCache	This pipeline saves the asset to the cache
DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename	Set the donwload filename header, if a download is requested.

This pipeline may be modified according to customer needs.

Extending the pipeline

If the pipeline is to be extended, for instance if some custom processing needs to be done to the image, then this may be done in between any of the steps above.

The pipeline step should have the following construction:

Code Block

language	c#

public class PipelineName : ProcessorBase<DFSMediaPipelineArgs>
{
	public override void Process(DFSMediaPipelineArgs args)
	{
		if (args.Result.StopPipeline)
        {
          return;
        }

        if (args.Request.Download)
        {
          return;
        }

        if (args.Result.Cached)
        {                       
          return;
        }
	    //code goes here
	}
}

Remember to include the custom step in the configuration file!

The object DFSMediaPipelineeArgs contains a Request and a Result. These two objects has the following properties:

Request

Parameter	Type	Description
AssetSiloId	string	Id of the asset silo from which the asset should be fetched
AssetId	string	Id of the requested asset
FormatId	string	Id of the format requested
DestinationId	string	Digizuite id of the destination - where to get the asset from
BaseUrl	string	BaseUrl of the Digizuite
AccessKey	string	AccessKey to the Digizuite
MimeType	string	Mimetype of the requested asset
Width	string	If a resize of the asset is requested, then this property contains the new width
Height	string	If a resize of the asset is requested, then this property contains the new height
Download	bool	If a download is requested, then this property is true
KeepAspectRatio	bool	if the aspect ratio should be kept, then this property is true
BoxFit	bool	If true, the resized image will not exceed the width and height. Will keep aspectratio.
UpscaleAllowed	bool	if upscale is allowed, then this property is true
Compress	string	If the image should be compressed, then this has a value between 0 and 100

Result

Parameter	type	Description
ResultPath	string	Path to the directory in which the asset is cached
FileName	string	Name of the cached asset
Cached	bool	Boolean to indicate whether the asset is cached
ResultStream	Task<Stream>	Handle for the result stream used to get the asset from Digizuite
ResizeBytes	byte[]	If the image is resized and/or compressed, this array contains the result bytes
DownloadUrl	string	Redirect URL for download requests
StopPipeline	bool	If the pipeline should be aborted, for instance due to security violation, then this is true
Asset	AssetIndexable	Asset model from the index
StatusCode	HttpStatusCode	Status code used to indicate the request status.
DownloadFileName	string	Containes the download filename.
DigizuiteAssetStreamUrl	string	Contains the digizuite url for the requested media.
IsVideo	bool	If true, the requested asset + quality is a video.

Manually deleting cache entries

The cache is invalidating if the image in Digizuite is re-transcoded. The cache invalidation results in all the entries for the given asset, being deleted. If one wishes to manually clear the cache this is also an option. There are two ways in which this can be accomplished:

Manually deleting the folder in the cache (i.e. delete the folder that has the asset ID of the asset that should be deleted).
Use the Administration DAM for Sitecore dashboard, it has a function called Image cache where you can delete the cache from through UI. DFS 11.1 - Administration dashboard

Enabling old resizing processor

From version DFS 11.1 the default resizing feature has been rewritten. The resizing it now done in Digizuite, this also requires that DAM version is minimum 5.10. If you are connecting to a DAM less then 5.10 and you are using the resizing feature, then you must enable the old resizing processor.

...

You must supply a width and height. The way these parameteres are used is based on the cropmode and the cropposition.

If the cropmode is PixelBased then crop width and crop height are interpreted as pixels. If the cropmode is AspectRatioBased then crop width and crop height are interpreted as an aspect ratio. For instance, for the aspect ratio 1:2, the image is cropped to the largest possible image with the given aspect ratio.

cropmode

*

How to interpreted the crop width and crop height.

PixelBased (default)
The crop width and crop height are interpreted as pixels.
AspectRatioBased
The crop width and crop height are interpreted as an aspect ratio.
For instance, for the aspect ratio 1:2, the image is cropped to the largest
possible image with the given aspect ratio.

Info
These values are case sensitivity

cropposition

*

When cropping, the focus point can be one of the following.

TopLeft
Top
TopRight
Left
Center (default)
Right
BottomLeft
Bottom
BottomRight

Info
These values are case sensitivity

outputimageformat

*

Control the output format, when resizing and or cropping. If this property is not set, the output format will be the same format as behind the quality property.
The valid output formats:

JpegImageFormat
AvifImageFormat
PngImageFormat
WebPImageFormat

Info
These values are case sensitivity

compress

*

Only applies to image assets.

Indicates whether the asset should be saved using a worse quality, thereby reducing the physical size.

from 0-100 is allowed, where 0 is the worst quality, but least physical storage.

options

*

Options is a dash ("-") separate list and can contain these options:

download - Will download the asset requested.

keepaspectratio - Will enforce aspect ratio on from the original asset, if a resize is requested.

boxfit - If a resize ia requested and you supplyed both the width and heigth. The resized image will not exceed these values and still keep the aspectratio.

upscaleallowed - Will allow upscaling an image. The default is to disallow that.

*Optional

Digizuite transcode system - fallback image

In digizuite DAM 5.10.x the transcode system has change DC 5.10 Breaking changes - Transcode system. What that means for the DFS connector is that, when requesting rendition that hadn’t been generated yet a fallback image will be returned and the statuscode is 202 (Accepted). The fallback image is of type svg and controlled by Digizuite. Once the rendition is ready in Digizuite is will be served to the mediahandler in Sitecore.

By default the DAM for Sitecore connector is configured to use the fallback logic, if the rendition is not ready. It is possible to disable this, so the request will stay open until the rendition is ready.

Note
Be aware if you disable the fallback image logic and you have alot og image on a page that has not been genereted. It will keep alot of TCP connections open and if the request take long time. You can end up in a situation where your Sitecore site dies.

To disable the fallback logic open the config file DFS.Settings.config and locate the setting property <setting name="DFS.MediaPipeline.UseFallbackImageIfUnavailable" value="true"/> change the value to false and reload the site. Now when requesting images that is not ready, the connection will stay open until it finishes.

Examples

Here are some use cases, that shows how the media handler works and how it is used in different situations.

This is the shortes url, these are the required parameters. Here we request the assetId 192 and the quality format id 3 (rendition from Digizuite).
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3

Resize the image to a width of 350 px and keep the aspect ratio of the height.
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3/resize/350x0

Resize the image to a width of 350 px and a height of 350 px. This will not respect the aspect ratio of the image.
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3/resize/350x350

Crop, this is the shortest use of the crop feature, this will set the cropmode to AspectRatioBased and then set the resizing width to 400 and the height to 100.
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3/cropsize/400x100

The above url would be the same as this.
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3/resize/400x100/cropsize/400x100/cropmode/AspectRatioBased

This will crop with an aspect ratio 4:1 and crop from the top left corner and then resize down to width 400 px and height 100 px.
/dfsmedia/baeefe6b74df44be8a2bccfb2c57af8e/192-3/resize/400x100/cropsize/400x100/cropmode/AspectRatioBased/cropposition/TopLeft

Understanding the DigizuiteMediaCache

The DigizuiteMediaCache is where everything, except videos, is saved. Below is a flow chart how it works when requesting media from the DFS mediahandler.

...

The cache location is configurable and is located in DFS.Settings.config

DFS.Settings.config

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <settings>
	  <!-- Path to DAM For Sitecore MediaCache. The following is supported: 
             -UNC (\\server\example\cahcepath)
             -Full path (C:\example\cachepath)
             -Relative path (/App_Data/cachepath)      
      -->
      <setting name="DFS.CacheLocation" value="/App_Data/DigizuiteMediaCache"/>
	</settings>
  </sitecore>
</configuration>

The default location is in the website root under App_Data/DigizuiteMediaCache/.

Files are cached based on the request made to the asset. An example request could be: http(s)://<sitecore url>/dfsmedia/29a605d46a3340418c16542f7272c3ec/110-50035

According to the specification of the URL, this request has the following properties:

AssetSiloId: 29a605d46a3340418c16542f7272c3ec
AssetId: 110
FormatId: 50035

The cache is then build using a naming scheme. Each asset is placed in a sub-folder which has the name of the assetid. In the case of the example, the path in which the file is saved would be App_Data/DigizuiteMediaCache/110

The filename is then constructed based on the given properties using the following scheme:

{Assetid}_{formatid}_{width}_{height}_{options}.{extension}

where width, height and options are not used, if not requested (i.e. not used in the example), which means in the example, the requested asset would have the following name:

110_50035.{extension}

The extension is retrieved from the file saved in the cache. The naming scheme enable unique names and hence the extension can be extracted from the file in the cache. Originally, the file is saved with the correct extension based on what is served from the Digizuite.

UNC path

The dfsmedia pipeline also supports having a centralized cache, which means multiple servers can have the same cache. This decreases storage, but also performance, because files are then cached on a UNC which is slower than having it locally. This is something each client has to have an opinion on.

Implementation

The new dfsmedia pipeline is implemented as a httphandler, using a pipeline in Sitecore. This pipeline is located in the DFS.Pipelines.config file:

DFS.Settings.config

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
	<pipelines>     
	 <DFS.Services.DFSMedia>      
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset, DFS.Client.Services" role:require="Standalone or ContentManagement" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuite, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SaveToCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename, DFS.Client.Services" />
      </DFS.Services.DFSMedia>
    </pipelines>
  </sitecore>
</configuration>

Each step is explained as follows:

Pipeline name	Description
DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset	This is only running in role:require="Standalone or ContentManagement". Will sync the asset into the asset silo if it does not exist.
DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity	Looks up the asset item.
DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache	This pipelines constructs a unique name based on the request and checks if the requested asset exists in the cache.
DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage	If resize is requested, the image will be resized.
DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuite	This pipeline executes the request towards Digizuite
DFS.Client.Services.Pipelines.DFSMedia.SaveToCache	This pipeline saves the asset to the cache
DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename	Set the donwload filename header, if a download is requested.

This pipeline may be modified according to customer needs.

Extending the pipeline

If the pipeline is to be extended, for instance if some custom processing needs to be done to the image, then this may be done in between any of the steps above.

The pipeline step should have the following construction:

Code Block

language	c#

public class PipelineName : ProcessorBase<DFSMediaPipelineArgs>
{
	public override void Process(DFSMediaPipelineArgs args)
	{
		if (args.Result.StopPipeline)
        {
          return;
        }

        if (args.Request.Download)
        {
          return;
        }

        if (args.Result.Cached)
        {                       
          return;
        }
	    //code goes here
	}
}

Remember to include the custom step in the configuration file!

The object DFSMediaPipelineeArgs contains a Request and a Result. These two objects has the following properties:

Request

Parameter	Type	Description
AssetSiloId	string	Id of the asset silo from which the asset should be fetched
AssetId	string	Id of the requested asset
FormatId	string	Id of the format requested
DestinationId	string	Digizuite id of the destination - where to get the asset from
BaseUrl	string	BaseUrl of the Digizuite
AccessKey	string	AccessKey to the Digizuite
MimeType	string	Mimetype of the requested asset
Width	string	If a resize of the asset is requested, then this property contains the new width
Height	string	If a resize of the asset is requested, then this property contains the new height
Download	bool	If a download is requested, then this property is true
KeepAspectRatio	bool	if the aspect ratio should be kept, then this property is true
BoxFit	bool	If true, the resized image will not exceed the width and height. Will keep aspectratio.
UpscaleAllowed	bool	if upscale is allowed, then this property is true
Compress	string	If the image should be compressed, then this has a value between 0 and 100
OutputImageFormat	string	Output format. See the above table for more details.
CropWidth	string	The crop width. See the above table for more details.
CropHeight	string	The crop height. See the above table for more details.
CropMode	string	The crop mode. See the above table for more details.
CropPosition	string	The crop position. See the above table for more details.

Result

Parameter	type	Description
ResultPath	string	Path to the directory in which the asset is cached
FileName	string	Name of the cached asset
Cached	bool	Boolean to indicate whether the asset is cached
ResultStream	Task<Stream>	Handle for the result stream used to get the asset from Digizuite
ResizeBytes	byte[]	If the image is resized and/or compressed, this array contains the result bytes
DownloadUrl	string	Redirect URL for download requests
StopPipeline	bool	If the pipeline should be aborted, for instance due to security violation, then this is true
Asset	AssetIndexable	Asset model from the index
StatusCode	HttpStatusCode	Status code used to indicate the request status.
DownloadFileName	string	Containes the download filename.
DigizuiteAssetStreamUrl	string	Contains the digizuite url for the requested media.
IsVideo	bool	If true, the requested asset + quality is a video.

Manually deleting cache entries

The cache is invalidating if the image in Digizuite is re-transcoded. The cache invalidation results in all the entries for the given asset, being deleted. If one wishes to manually clear the cache this is also an option. There are two ways in which this can be accomplished:

Manually deleting the folder in the cache (i.e. delete the folder that has the asset ID of the asset that should be deleted).
Use the Administration DAM for Sitecore dashboard, it has a function called Image cache where you can delete the cache from through UI. DFS 11.1 - Administration dashboard

Enabling old resizing processor

From version DFS 11.1 the default resizing feature has been rewritten. The resizing it now done in Digizuite, this also requires that DAM version is minimum 5.10.5. If you are connecting to a DAM less then 5.10.5 and you are using the resizing feature, then you must enable the old resizing processor.

Open the DFS.Pipelines.config and look for the pipeline DFS.Services.DFSMedia. This is the default configuration where the new resizing processor is enabled.

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
	<pipelines>     
	 <DFS.Services.DFSMedia>      
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset, DFS.Client.Services" role:require="Standalone or ContentManagement" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuite, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SaveToCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename, DFS.Client.Services" />
      </DFS.Services.DFSMedia>
    </pipelines>
  </sitecore>
</configuration>

To enable the old processor, delete the processor <processor type="DFS.Client.Services.Pipelines.DFSMedia.NewResizeImage, DFS.Client.Services" /> and add this processor <processor type="DFS.Client.Services.Pipelines.DFSMedia.ResizeImage, DFS.Client.Services" /> in between GetMediaFromDigizuite and SaveToCache.

It should look like this.

Code Block

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
	<pipelines>     
	 <DFS.Services.DFSMedia>      
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.SynchronizeAsset, DFS.Client.Services" role:require="Standalone or ContentManagement" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.LoadAssetEntity, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromCache, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.NewResizeImageGetMediaFromDigizuite, DFS.Client.Services" />        
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.GetMediaFromDigizuiteResizeImage, DFS.Client.Services" />       
         <processor type="DFS.Client.Services.Pipelines.DFSMedia.SaveToCache, DFS.Client.Services" />
        <processor type="DFS.Client.Services.Pipelines.DFSMedia.ResolveFilename, DFS.Client.Services" />
      </DFS.Services.DFSMedia>
    </pipelines>
  </sitecore>
</configuration>

...

Versions Compared

Old Version 8

New Version Current

Key

Understanding the DigizuiteMediaCache

DFS.Settings.config

UNC path

Implementation

DFS.Settings.config

Extending the pipeline

Manually deleting cache entries

Enabling old resizing processor

Digizuite transcode system - fallback image

Examples

Understanding the DigizuiteMediaCache

DFS.Settings.config

UNC path

Implementation

DFS.Settings.config

Extending the pipeline

Manually deleting cache entries

Enabling old resizing processor