Aprimo Content Selector

Introduction

The Aprimo content selector is a pre-built UI to use Aprimo DAM as a tool for users to select content items in 3rd party systems.

Content Selector

Usage

To open the Aprimo DAM in Content Selection mode you need to call a dedicated endpoint:
https://<tenant>.dam.aprimo.com/dam/selectcontent

The Aprimo Content Selector can only be used in a stand-alone browser window (or browser tab).

If the user is not yet logged in to Aprimo, he will first be redirected to the login page. After successfully authenticating, the user will be presented with the Aprimo Content Selector and can start selecting content items.

Once the user has made a selection and clicked the button that accepts his selection, the Aprimo Content Selector will call the opener back using the postMessage API provided, which is supported by all modern browsers (see documentation on MDN ).

Options

The Aprimo Content Selector can be customised with following options:

Option Data type Description Default
title string The title to display in the Aprimo ContentSelector Adapts to select option
description string The description to display in the Aprimo ContentSelector (no description)
accept string The label of the button to confirm a selection 'Select'
limitingSearchExpression string A DAM search expression to control the presented content items. The context of the search expression is always Record. See Searching for records for more information. '*'
select ‘single’ or ‘multiple’ Specifies whether the user can select one or more content items 'multiple'
dialogMode ‘fullscreen’ or ‘default’ Specifies the dialog mode of the content selector. This controls the placement of the dialog buttons: default puts the buttons at the bottom, fullscreen puts them in the header bar 'default'
facets string[] An array of facet names to use in the Aprimo Content Selector. The specified facet names must refer to registered facets and the names are case sensitive. When no facets are specified, the facets configured for search will be used. To disable facets, specify an empty array. (no value)
targetOrigin string Specifies what the origin of targetWindow must be for the event to be dispatched (see documentation on MDN ) '*'

To provide the options to the Aprimo Content Selector, you must construct a JSON object containing the options you want to control and convert it into base64-encoded string. As an example:
const selectorOptions = {
title: 'Select logo',
description: 'Select the logo that will be used on the printed brochure',
limitingSearchExpression: 'classification.id = 3a6499d4865f446b8711a8b90098ec55',
accept: 'Use this logo',
select: 'single'
}
const tenant = '<tenant name>'
const encodedOptions = window.btoa(JSON.stringify(selectorOptions))
const url = `https://${tenant}.dam.aprimo.com/dam/selectcontent#options=${encodedOptions}`
document.write(`<a target='_blank' href='${url}'>Show selector</a>`)

Dealing with Special Characters

When your JSON object contains property values with characters outside of the Latin1 range, you cannot use the browser’s window.btoa method. To circumvent this, you can use a little trick by first using the encodeURIComponent method before using the btoa method. To optimize the size of the string, you must apply an unescape as well.
function encode(stringToEncode) {
return window.btoa(unescape(encodeURIComponent(stringToEncode)))
}

Callback

When the user clicks either the accept or cancel button in the Aprimo Content Selector, the selector will perform a callback to the originating window, in the browser. To achieve this communication, the postMessage API is used. In order to handle this communication, you need to listen for message events.
window.addEventListener("message", handleMessageEvent, false)

Note: these messages don’t always work correctly when running a page at a file:// URL

The event.data will contain a JSON object, which specifies the following properties:

Property Data type Description
result string Contains either 'accept' or 'cancel', indicating the button the user clicked on
selection Selection[] When the user clicked the accept button, the selection property will contain an array of Selection objects. When the user canceled the operation, the selection property will be undefined. The id property of the Selection object is the record id of the selected record in DAM.

The TypeScript definition of the Selection object is:
interface Selection {
id: string
}

Example implementation

<button id="openSelector">Open selector</button>
<script>
const tenantUrl = 'https://sometenant.dam.aprimo.com'
const aprimoContentSelectorUrl = tenantUrl + '/dam/selectcontent#options=<encoded options>'
const handleMessageEvent = (event) => {
// Ensure only messages from the Aprimo Content Selector are handled.
if (event.origin !== tenantUrl) {
return
}
if (event.data.result === 'cancel') {
alert('You have canceled the selector')
} else {
const ids = event.data.selection.map((selection) => selection.id)
alert("You have selected following ids:\n\n" + ids.join('\n'))
}
}
const openSelector = () => {
window.open(aprimoContentSelectorUrl, 'selector')
}
window.addEventListener("message", handleMessageEvent, false)
const button = document.getElementById('openSelector')
button.addEventListener('click', openSelector)
</script>

Note that the Aprimo Content Selector will automatically close the browser window.