Aprimo

Details an integration available for Aprimo, built and maintained by Umbraco HQ.

This integration provides a custom Media Picker for digital assets managed in an Aprimo workspace. It can be used as a property editor for content. A value converter providing a strongly typed model for rendering is available, along with a sample rendering component.

Package Links

• NuGet install

• Source code

• Umbraco marketplace listing

Minimum version requirements

To ensure compatibility, check the Dependencies tab on NuGet for the required Umbraco CMS version. For example, see Umbraco.Cms.Integrations.DAM.Aprimo.

Configuration

The following configuration is required to connect to the Aprimo Digital Asset Management (DAM) workspace:

appsettings.json

{
  "Umbraco": {
    "CMS": {
      "Integrations": {
        "DAM": {
          "Aprimo": {
            "Settings": {
              "Tenant": "[your_tenant_name]"
            },
            "OAuthSettings": {
              "ClientId": "[your_aprimo_client_id]",
              "ClientSecret": "[your_aprimo_client_secret]",
              "RedirectUri": "https://[your_website_base_url]/umbraco/api/aprimoauthorization/oauth",
              "Scopes": "api offline_access"
            }
          }
        }
      }
    }
  }
}

The configuration is split into two components:

• A generic one that holds your tenant's name, and

• One for OAuth settings.

The authorization process is managed using the OAuth flow - Authorization Code with Proof Key for Code Exchange (PKCE). When making a request for an access token, you will need to generate a code verifier and a code challenge.

Client Id and Client Secret details are retrieved from your Aprimo Client Registration, which you will need to set up with the redirect URI pointing to the AprimoAuthorizationController - OAuth action.

Using the offline_access scope, the response from Aprimo API will contain a refresh token, with an expiration period of 10 days. This will keep the API access available for the front-end rendering of the images.

Backoffice usage

To use the Media Picker, a new Data Type should be created based on the Aprimo Media Picker property editor.

If the configuration is not valid, an error-tag will be displayed in the right upper corner of the configuration box.

Otherwise, you will be able to select one of the two available options for picking assets:

• Aprimo API - items are retrieved using the API and an overlay of the property editor will display the list of available items in the Digital Asset Management (DAM) workspace.

• Aprimo Content Selector - rich UI tool hosted on Aprimo Cloud where you can pick items using a familiar Aprimo interface.

Browser information

Before using the integration with Aprimo, please make sure to use a browser that is supported by Aprimo Cloud. Without one you will not be able to authenticate, nor use the Content Selector.

Aprimo currently supports these browsers, but make sure to check this topic for an updated list:

• Chrome for Windows and Macintosh

• Edge (Windows 10 only)

• Internet Explorer 9, 10, and 11

• Safari 6, 6.1, 6.2, and 7.0 (Macintosh only)

Front-end rendering

A strongly-typed model will be generated by the property value converter. An HTML helper is available to render the asset on the front end.

Make sure your template has a reference to the following using statement:

@using Umbraco.Cms.Integrations.DAM.Aprimo.Helpers;

Assuming a property based on the created Data Type with the alias aprimoMediaPicker has been created, render the media asset:

@Html.RenderAprimoAsset(Model.AprimoMediaPicker)`

Properties available from the strongly-typed model:

• Title

• Thumbnail

• Crops

• Asset fields

Working with Crops

For the selected media asset you can retrieve the details of the crops using the MediaWithCrops object.

It contains:

• Details of the original asset,

• The list of available crops, and

• A method to retrieve the crop URL based on name and width/height.

For example:

• To get the URL for crop item with the name Social: @Model.MediaWithCrops.GetCropUrl("Social")

• To get the URL for crop item with height 1080: @Model.MediaWithCrops.GetCropUrl(null, 1080)

Working with fields

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.

For example, to get values for a field with the label Display Title:

var displayTitle = @Model.Fields.FirstOrDefault(p => p.Label == "Display Title");
var values = displayTitle != null
                ? displayTitle.Values 
                : default(Dictionary<string, string>());