DFE 2.3.0 - 1 Understanding DAM For Episerver
- Martin Ulisse
The Digizuite™ DAM for Episerver connector is a fairly large and advanced integration with many moving parts.
The goal for this chapter is to give a bit of a basic understanding of how the parts fit together. Some concepts require deeper explanation and examples and they are split into their own chapters, following this.
The DigizuiteClient
A central component to the integration is the DigizuiteClient. It's exposed through dependency injection using it's interface, IDigizuiteClient and is a singleton. It is the central point that all the other components of the integration use for the actual connection and configuration to the DAM Center. If you, as a developer, need to do code that, for example, queries the DAM for specific assets, you'll most likely find the need to use the ServiceLocator in Episerver to get an instance of IDigizuiteClient and use that as your starting point.
The DigizuiteClient initializes itself by connecting to various services in the DAM Center and fetches relevant configuration and settings defined in the DAM. For example, which languages, media formats, sort orders, media types, metadata and crops that are available. It then also retrieves the DAM's "Media Manager Menu" tree structure which is exposed in Episerver as the folder structure of the assets.
But - it's also in charge of numerous other important tasks:
- Keeping track of the individual service connectors to DAM Center and their assigned languages.
- Caching relevant in-memory data
- Client notifications
- Connection status in case of resilience needed for unstable DAM connections
- It contains the main methods used for all CRUD interactions with the DAM center.
- It builds the proper Episerver content objects for the corresponding assets
- Handling uploads
- In-memory draft storage of asset metadata changes
- Much, much more...
DigizuiteContentProvider
The content provider is the main class that plug into Episerver's provider pattern to expose assets and folders in Digizuite DAM as if they were Episerver content.
By default, it's registered programmatically by an initialization provider and attached to an entry point created below the main "Global Assets" folder in Episerver, named "Digizuite". However that can of course be customized - and you can even choose to register it your self. It contains the needed methods to return the proper content given a content reference, GUID or URL pointing to a content element in this provider as well as methods to return directory listings and handle upload, save, delete and many more operations.
For most of its logic, it will essentially encapsulate logic provided by the aforementioned DigizuiteClient.
ID's and GUIDs
In Episerver, all content typically have both a ContentReference and a GUID - and in some cases a URL. The DAM Center typically exposes only an AssetId (int) or a folderId (int). In order to easily map these over to Episerver ContentReference (that also has an int ID) the convention has been made that negative ID numbers are folders and positive ID numbers are assets. To ensure a uniform way of dealing with this - even if the future changes this approach, there is a helper class called ConversionHelper that provides methods to easily convert between the needed formats.
The GUIDs are slightly more tricky. For the content provider to work well, it needs to be able to quickly identify if a given GUID belongs to the current provider, and if so - which corresponding asset ID should be looked up. As this lookup happens many times per request, it isn't feasible to do a database mapping lookup every single time. Instead, the integration uses a 'base' GUID defined in configuration and simply stores the int ID in the first 4 bytes (32-bit) of the GUID. The ConversionHelper also contains methods for dealing with this. However, under normal circumstances, you shouldn't need to go to the level of complexity and to indicate that, those methods are in an "internal" namespace.
Drafts and versioning
The DAM Center doesn't support the same concept of draft/versioning/publish as Episerver does. In Episerver, every single change results in a new draft version being created or saved, where as, in the DAM Center, changes are not saved unless you actively decide to press "Save". In order to support updating metadata fields in the DAM from Episerver, the DigizuiteClient will instead keep track of the changes in-memory, until the editor decides to publish - at which point, the changes will be sent back to the DAM Center and the asset is updated.
Folder hierarchy
Once again, the DAM Center and Episerver have slightly different opinions on the concept of a folder structure. Where in Episerver it's important that every single content item lives under exactly one parent. The Digizuite DAM considers the folder nothing but a metadata attribute for the asset that you filter on. This means that all assets from Digizuite exist just beneath the root (entry point in Episerver) but also can be visible in one or more sub-folders.
Cropping and Crops
The DAM Center has a series of predefined crop settings with different aspect ratios (that can be changed in the DAM Center). Typically named something like "Square", "Banner", and "Widescreen". These are the crop types you can create for the various images. In Episerver, just as in the DAM Center, they will appear as separate assets/content objects, but, if a content object is the crop of another content object, it will hold a reference to the 'parent' in its properties, and will have the name of the crop listed in its "CropName" metadata property.
Media Formats
Media formats, on the other hand, are more to be considered different views or blobs of the same asset/content object. The DAM Center also has a predefined list of media formats which is used for the different asset types (video, images, PDF, and so on). Upon upload, it will automatically create asset using one of the miscellaneous predefined media formats. In Episerver, media formats are either exposed as Blob properties on the asset content model (and can be accessed directly via the URL) or they can be fetched using one of the extension helper methods.
More info on this subject:
Caching
The DAM For Episerver integration heavily relies on cache to improve performance. The caching mechanism has multiple working parts:
- Binary Disk Cache. Most media assets (except for videos) are cached lazily on the disk in the Episerver blob storage area. When an asset is requested from the blob provider, it will always use the cached asset from the local disk before attempting to fetch it from Digizuite DAM.
- Binary Disk Temporary Upload Cache. When an editor uploads files to Episerver, that are intended to be sent onwards to Digizuite DAM, they will temporarily be stored in the "DigizuiteTemp" (configurable) folder below App_Data. Afterward, a background process will forward them to Digizuite DAM without slowing down the editorial experience. After a successful upload to Digizuite DAM, the temporary files are automatically removed.
- In-memory Asset Metadata Cache. The Digizuite Client, which retrieves all metadata, automatically caches asset metadata in memory, using the Episerver Synchronized Caching mechanism.
Resilience
Besides caching, which has the main purpose of improving performance, there is Resilience, which has the task of improving stability in case of failure scenarios. The general philosophy behind the Digizuite/Episerver integration is that: Should the connection fail between the two systems, for whatever reason, it must never result in a site crashing. Furthermore, the site should also still show main assets and it should be possible to work in edit-mode - albeit without full Digizuite functionality.
The diagram below shows the flow when loading content. First we look at the in-memory cache, then we look into the database. We have our own table (DigizuiteContentItems) where we store all the metadata for the content item. If it is not in the database, we fetch the data from the Digizuite API and store the data in the database and the cache. With this approach, we ensure that the content always is available in a scenario where the connection between Digizuite DAM and Episerver is lost. The data will in this case ,of course, be saved to the database.
On top of that, all components of the integration has been made robustly, so that even if they are in a failure scenario, they will not crash - but rather report errors (both in the error logs and make editor notifications) - but still offer functionality, albeit very limited.