What is a DAM?
A digital asset is content stored in a digital file format. Digital assets include photos, videos, images, audio clips, documents, and any other content that provides value to the company that owns or has the right to use it. Organizations that handle a lot of digital assets such as images, product sheets, videos, graphics, and more, increasingly rely on digital asset management (DAM) solutions. A DAM will provide centralized and improved management of the assets, plus the workflows to support them.
A DAM system works as a central repository and control center for uploading and organizing digital assets, and then users or automation tools tag the files with metadata. Metadata is information that describes an asset and enables system users to search and find files in the system in an efficient way.
Aprimo DAM Experience
Aprimo is a provider of digital asset management and content operations software that, with its robust Marketing Resource Management (MRM) suite, enables content personalization at scale, deeper insights from creative operations and content performance to inform strategy, and seamless handoffs from content creation to distribution.
The products portfolio includes Digital Asset Management (DAM), Work Management, and Marketing Budget Management bringing Aprimo the “Leader” recognition for 2022 from Forrester based on this report.
If you want to find out more about the DAM solution from Aprimo, and see some of the included features, add-ons or integrations, please check out this page or start exploring the Aprimo solution with a self-guided, self-paced, multi-user free trial, which you can sign up for here.
Using Aprimo with Umbraco CMS
To start using Aprimo with Umbraco CMS you will first need to retrieve an identifier for your workspace from Aprimo, called tenant. This is a key configuration item that enables you to access the digital assets from Aprimo directly from the browser, by accessing https://[tenant].dam.aprimo.com/dam or using the Umbraco CMS integration.
Next you need to make sure that you are authorized and can access the Aprimo DAM REST API. Please follow along as I walk you through the setup in the next section.
Authorization Overview
Aprimo supports several different authorization types, but the one used with this integration is OAuth flow - Authorization Code with PKCE.
You have to keep this in mind when preparing the authorization setup on Aprimo. This is because you will need to have an Aprimo Client Registration available, (Aprimo team will help you out with this process) to have the necessary OAuth settings available.
Configuration
Integrating Aprimo with Umbraco CMS is just a few clicks away …
- Install the NuGet package
- Add the following configuration:
Browser Support
To take full advantage of the Aprimo experience, please make sure that you are using a browser that is compatible with Aprimo Cloud, as they currently do not support Mozilla Firefox and Microsoft Internet Explorer.
You can always check for the updated list of accepted browsers here.
Using a browser that is not supported will result in a poor user experience and usability issues, as you will not be able to authenticate or select content using the Aprimo Content Selector.
A warning message will be displayed in the data type configuration view will signal this:
and you'll also see it in the Aprimo interfaces:
Working with Digital Assets
Current integration provides a tool for selecting digital assets from an Aprimo workspace using a custom Property Editor called Aprimo Media Picker.
Its configuration allows editors to access the media items in two ways:
Aprimo DAM REST API
Assets are retrieved using an Umbraco interface communicating with the API. This will work with all browsers supported by Umbraco as long as there is a valid access token and refresh token to authorize requests. Using this option you can search items by title only.
Aprimo Content Selector
Assets are retrieved using a richer Aprimo user interface, but is only available with the list of supported browsers. This option allows you to use the advanced filtering options from Aprimo.
This option further allows you to use the advanced filtering options from Aprimo:
Rendering Aprimo assets
A rendering component is available for displaying the selected asset using a strongly-typed model generated by the property value converter.
You just need to add this using statement to your view: @using Umbraco.Cms.Integrations.DAM.Aprimo.Helpers; and render the asset using the HTML helper: @Html.RenderAprimoAsset([your_model_property]).
The view model will supply you with details on the asset’s title, thumbnail, crops, and fields.
For the selected media asset you can retrieve the crop's details using the MediaWithCrops object. It contains the details of the original asset, the list of available crops, and a method to retrieve the crop URL based on name and width/height.
The asset's fields are grouped in an object containing their label and a dictionary of values based on the available cultures for that asset.
And the result might look something like this - you can supply a rendering component of your own, or use the available CSS classes on the tags for a styling matching your desire.
Building the Aprimo DAM integration - Brick by Brick
The Aprimo Media Picker integration makes it easy to use assets in the Umbraco backoffice. This was done using Aprimo's mature and well-documented API layer. Here I’ll briefly cover some of the interesting concepts used for the integration, along with links if you want to dive deeper.
Search with Aprimo DAM REST API
In Aprimo DAM REST API, all resources have a unique URL assigned. The base URL for accessing resources is https://[your_tenant].dam.aprimo.com/api/core/ and the returned data is composed based on a set of request headers.
These headers are called Aprimo Select Headers and can be used to return additional information on the records. The selecting feature is used in the Aprimo DAM REST API to support the dynamic nature of the Aprimo DAM resources and to provide the API consumers with a way to select a custom granularity level for the resource representation they want to retrieve from Aprimo DAM.
The general format of the select parameter is: "Select-{Resource}: SubResource1,SubResource2,SubResource3, ..." where the value is a comma-separated list of subresources to be included in the resulting resource representation.
Searching for records
A request is sent to /search/records with the following headers:
- page
- pagesize
- select-record: title,thumbnail
The request body specifies that we want all the assets with aReleased status
Searching for records by search term
A request is sent to /search/records with the same headers from point 1, but the body changes to:
Searching for record by id
A request is sent to /record/[id] with the following headers:
- select-record: title,thumbnail,fields,masterfileversion
- select-fileversion: renditions
- select-rendition: publiclinks
This will tell the API to send back the record found by ID, with its fields and their values, the media crop items and their public CDN links.
How PKCE works
Proof Key for Code Exchange (PKCE, pronounced “pixie”) is an extension to the authorization code flow to prevent CSRF and authorization code injection attacks. When making a request for an access token, a code verifier and a code challenge are generated, and used when exchanging the authorization code for an access token. This way, if the code is intercepted, it will not be useful since the token request relies on the initial secret.
Please check out this blog post if you want to learn more.
A breakdown of the user workflow:
- User clicks Connect to authenticate with Aprimo.
- The integration creates a cryptographically-random code_verifier and from this generates a code_challenge using this helper:
3. User is redirected to the Aprimo login page along with the generated code_challenge.
4. The OAuth server stores the code_challenge and redirects the user back to the website with an authorization_code.
5. A request is made for the access token and refresh token to the OAuth server passing the authorization_code and the code_verifier generated at step 2.
6. The OAuth server verifies the code_challenge and code_verifier .
7. The OAuth server responds with an access token and a refresh token which are persisted in the aprimoOAuthConfiguration table.
Because one of the scopes is offline_access, the returned refresh token will be used to exchange with a new access token, when the one saved in the database expires and we receive a 401 - Unauthorized response from Aprimo API.
An Aprimo API refresh token can have an expiration date that varies from 1 hour to 10 days (10 days being the maximum time span). To avoid situations where the API is not queried for a bigger period of time, and you would need to reconnect with your account, a greater expiration date for the refresh token would be recommended. This way you can ensure your users of a smooth and uninterrupted experience working with the digital assets.
Redirects from the authorization server will be handled by exposing an endpoint in an UmbracoApiController that will use the authorization code for retrieving the access token and the refresh token.
Conclusions
Working with a DAM system was particularly interesting, as I explored new boundaries for Umbraco as a Composable DXP platform. Working with Aprimo was also a pleasent experience, especially being able to scale the search for digital assets from your Umbraco backoffice makes the use case of Aprimo relevant for users of Umbraco.
Working with the Aprimo integration for Umbraco also introduced me to an extended security layer to OAuth flows with PKCE and how to go about this extra layer in the use case of accessing the Aprimo Media Picker from Umbraco backoffice .
As usual, the integration is open-sourced here and your input is more than welcome.
The integration, including the Aprimo Media Picker and rendering component, is available on the Umbraco Marketplace and NuGet.
You can also follow up with similar integrations in the PIM & DAM section of the Marketplace.
