The Digizuite™ DAM for Episerver connector consists of 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 requires 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.
...
- Keeping track of the individual Service 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 content objects for the corresponding Assetsassets
- Handling uploads
- In-memory draft storage of asset metadata changes
- Much, much more...
...
The content provider is the main class that plug into Episervers Episerver's provider pattern to expose assets and folders in Digizuite DAM as if they were Episerver Contentcontent.
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, called 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 GUID or Url URL pointing to a Content content element in this provider as well as methods to return directory listings and handle upload, save, deletes delete and many more operations.
For most of it's its logic, it will essentially encapsulate logic provided by the before mentioned aforementioned DigizuiteClient.
ID's and GUIDs
In Episerver, all content typically have both a ContentReference and a Guid GUID - and in some cases a urlURL. 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 both needs to be able to quickly identify if a given GUID belongs to the current provider, and if so - which corresponding asset -id 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.
...
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 click press "Save". In order to support updating meta data metadata fields in the DAM from Episerver, the DigizuiteClient will instead keep track of the changes in-memory, until the editor decides to Publish 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 has have slightly different opinions on the concept of a folder structure. Where it in Episerver is it's important that every single content item lives under exactly 1 one parent, . The Digizuite DAM considers the folder nothing but a meta-data metadata attribute for the asset that you can filter on. This means that all assets from Digizuite lives under exist just beneath the root (entry point in Episerver) but also can be visible in one or more child 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" and so on. These are the crops that crop types you can create for the various images. In Episerver, just as in the DAM Center, they will appear as seperate separate assets/content objects, but, if a content object is a the crop of another content object, it will hold a reference to the 'parent' in it's its properties, and if will have the name of the crop listed in it's its "CropName" metadata property.
Media Formats
Media formats, on the other hands hand, are more to be considered different views or blobs of the same asset/content object. The DAM Center will also have has a defined predefined list of media formats to be made available 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 different miscellaneous predefined media formats. The In Episerver, media formats are in Episerver either exposed as Blob properties on the asset content model (and can be accessed directly in via the urlURL) or they can be fetched using one of the extension helper methods.
Learn moreMore info on this subject:
...
- Binary Disk Cache. Most media assets (except for videos) are cached lazily cached on the disk in the Episerver blob storage area. When an asset is being 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 should are intended to be sent on onwards to Digizuite DAM, they will temporarily be stored in the "DigizuiteTemp" (configurable) folder below App_Data. ThenAfterward, a background process will send forward them to Digizuite DAM without slowing down the editorial experience. After a successful upload to Digizuite DAM, the temporary files will be are automatically removed.
- In-memory Asset Metadata Cache. The Digizuite Client that , 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 is there to improve has the task of improving stability in case of fault failure scenarios. The general philosophy behind the Digizuite/Episerver integration is that should : Should the connection fail between the 2 two systems, for whatever reason, it should 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 DBdatabase, then we fetch the data from the Digizuite API and stores store the data in the DB database and the cache. With this approach, we make sure ensure that the content always will be available if is available in a scenario where the connection between Digizuite DAM and Epi Episerver is lost and off cause the data has been save . 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 robustrobustly, so that even if they are in a fault failure scenario, they will not crash - but rather report an error errors (both in the error logs and make editor notifications) - and but still offer functionality, albeit very limited functionality.