Aprimo Media Picker For Umbraco Aprimo Workspace 1917X1002px

Integrating Aprimo DAM with Umbraco CMS

The eagle may soar; beavers build DAMs

Adriancojocariu 500X500
Written by Adrian Cojocariu

In this article, we will explore the new integration between Aprimo and Umbraco CMS and how it can help you achieve better digital asset management (DAM). We’ll walk you through the setup process, including authorization overview and configuration steps. We’ll also discuss different ways to work with digital assets using the new Aprimo Media Picker, including options for searching and filtering assets, rendering, and more. So, if you're looking to optimize your digital asset management and enhance your content creation and distribution workflows, this blog post is a must-read. Let's dive in and explore the new integration!

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.

Aprimo Media Picker For Umbraco Aprimo Workspace 1917X1002px

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.


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:

Aprimo Media Picker For Umbraco Data Type Configuration Unsupported Browser 1560X645px

and you'll also see it in the Aprimo interfaces:

Aprimo Media Picker For Umbraco Property Editor Unsupported Browser 1425X743px

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:


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 Media Picker For Umbraco Aprimo API 912X1007px

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.

Aprimo Media Picker For Umbraco Aprimo Content Selector 1914X1011px

This option further allows you to use the advanced filtering options from Aprimo:

Aprimo Media Picker For Umbraco Aprimo Content Selector Advanced 1569X849px

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.

Aprimo Media Picker For Umbraco Rendering Assets 1411X988px

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

Aprimo Media Picker For Umbraco - search expression released_495X140px

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:

Aprimo Media Picker For Umbraco - search expression term_364X151px

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:

  1. User clicks Connect to authenticate with Aprimo.
  2. 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.


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.

Loved by developers, used by thousands around the world!

One of the biggest benefits of using Umbraco is that we have the friendliest Open Source community on this planet. A community that's incredibly pro-active, extremely talented and helpful.

If you get an idea for something you would like to build in Umbraco, chances are that someone has already built it. And if you have a question, are looking for documentation or need friendly advice, go ahead and ask on the community forums.

Want to be updated on everything Umbraco?

Sign up for the Umbraco newsletter and get the latest news and special offers sent directly to your inbox