Category: Digital Asset Management

If you want to find a specific record or to retrieve a collection of records, for example in custom code, references or XML settings, you can build search expressions using a number of searchable properties. This topic lists all properties that you can use and guides you in how to construct search expressions to find records.

In the Searchable properties on records list below you will see both simple and complex searchable properties. Simple properties are of a simple data type, like a string, number or datatime. Complex properties contain nested ADAM objects, such as a classification, file or user. In case of a complex property you can use the searchable properties of that nested object to complete your search expression. Click each of the complex properties in the table to go to the list of searchable properties for that object type.

An example:

Suppose you want to retrieve all records that are linked to a certain classification. You can use any searchable property of the nested classification object to specify which classification you want to use in the search expression, in order to find all records that are linked to that classification.

You can find all searchable properties for classification in Classification.

Relation record-classificationRelation record-classification

So, to search for all records that are linked to the classification named ProductImages you could use this search expression:

Classification.Name = ProductImages

The Sortable column indicates for each property if it can be used for sorting, for example to sort a search result set, in record display view configurations or when creating widgets.

Next to the predefined actions that are available in Aprimo DAM on records and collections, you might want to create some custom ones that fit your business process better. To do this Aprimo provides PageHooks, which are buttons and links that can be configured to launch external applications from within the Aprimo UI. They make it possible to use an external service or application to extend the default functionality of Aprimo DAM. PageHooks can be used to simply pass data to an external application, e.g. to start an approval process, or to process record data in more advanced ways and return the result to Aprimo DAM.

Aprimo DAM simply sends a request and then waits for the external application or service to process it and return a response. DAM acts on this response, from simply showing a success message to redirecting the user to a third party application, which can be opened either in the same window or in a new window.

In Aprimo DAM PageHooks currently only work with records and collections.

How does it work

A user clicks the custom action in Aprimo DAM in the action menu of either a single record, a selection of records, or in a collection. This action then posts the record or collection id(s), along with the URL of the current page, the location in which to open any response URL and an authorization code (if necessary), to the application endpoint that was specified in the PageHook, e.g.

Contents of a PageHook request
Contents of a PageHook request

The external application or service can then start processing the request. If an authorization code was included, the external application can use this to authenticate and communicate with the DAM API, using the current user’s account.

Except for the record/collection Ids, the PageHook does not send any other DAM data to the external application. It’s up to the endpoint to query the DAM REST API for the additional data it needs.

When the external application has done its work, it sends a response back to DAM: either just a notification that the data was received successfully, an error message if anything went wrong or a response URL. If there was no URL in the response, Aprimo DAM simply shows a “Success” flyout or the returned error message. If there was a response URL the user is redirected to that URL. Depending on the settings in the PageHook this URL is opened in the same window or in a new one, either refreshing the window or redirecting the user to a different browser window.

Opening the response URL in the same window is recommended if the external application changes data or content in the record where user triggered the action. If the response URL is the same one as the page where the action was clicked, it will simply refresh the record details so the user can see the effects of his action.

Another use case for same window could be redirecting the user to a custom wizard, e.g. to start an approval process on a record in DAM. The wizard takes the user through a series of data collection steps, collecting the data that is required in the approval application but should not be stored in DAM. The external application then retrieves any other necessary data from DAM and submits everything to the approval application for further processing. It ends by either redirecting the user back to a page in DAM or to the item in the approval application, depending on the business process.

If the URL is set to open in a new window, DAM just opens that window and posts the data. The external application is responsible for the contents of that window and DAM is not involved in the processing anymore. The existing DAM window will continue to function normally. A use case could be, for example, publishing a file to a social media channel. In this case the action pops up a new window, the custom code receives the Ids of the record where the action was clicked, queries the DAM REST API for additional data, and uses this data to talk to the API of the social media channel. The user only sees a new window with a prepopulated submission screen from the social media channel.

Steps to create a custom action using PageHooks

These steps need to be done to create a custom action using a PageHook in DAM:

  1. (optional) Register the external application or service Aprimo MO
  2. Develop the external application or service
  3. Add the custom action to Aprimo DAM
  4. Add translations for the action label for all UI languages in Aprimo DAM

(optional) Register the external application or service in Aprimo MO

Use the Registrations list in the Integration area of Aprimo MO to identify the external applications that can communicate with Aprimo. This is only necessary if the external application needs to authenticate to get data from within DAM.

You can find the Registrations list in System Administration > System Tools > Integration > Registrations.

More information on how to create an application registration is available in https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module3 , in step 1.

Develop the external application or service

PageHooks can work with all kinds of applications or services, like web services, Azure Functions, etc. The only prerequisite is that they should be able to accept HTTP requests from DAM.
You will need the endpoint URL of this service or application to use it in a custom action.

How to authenticate

When the external application gets the request, it will probably need to get more detailed information about the record(s) or collection the action was started from. To be able to do this the application or service needs to authenticate. This can be done either using the user account that clicked the action, or with an integration account of the application itself.

If you want to use the user account that triggered the custom action, configure the PageHook so that it includes an authorization code and the client id (see further). You can then use these to get an authentication token back from Aprimo MO, which you can use to authenticate with DAM and get the data you need. Follow this process  https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module3, but only step 1 (where you register the application to get a client id, see before).

Include these headers in the POST request to get an authentication token back from Aprimo MO:

If you want the application to log in under its own “integration” account, follow all of the  steps in https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module3. This also means that you don’t need to configure the PageHook to include an authorization code and client id (see further).

Get record/collection data via the ADAM REST API.

Use the ADAM REST API to get record or collection data from within DAM, using the record Id(s)  or collection Id from the request.

You can find more information on how to use the ADAM REST API in https://training.dam.aprimo.com/api/core/docs

Add the custom action in Aprimo DAM

There are several record or collection-related action menus in Aprimo DAM, and each of them is managed in a separate system setting in ADAM System; If you want to add a custom action, you have to add it in each of the action menu settings where you want it to appear. The settings are:

For records:

For collections:

To add a custom action that uses a PageHook you edit the appropriate setting in ADAM System, and you add this line in the list of actions in the XML structure:

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”MyCustomAction”
       include=”auth-code”
       url=”[service url]”
       location=”[self | new]”
       clientId=”[client id]” />

where:

For more information on these action menu settings and the action menu structure you can use the Help link in each of these settings or go into ADAM Help > Administrator Guide > Configuration areas > UI configuration in ADAM studios > Configuring action menus for records and collections.

Provide translations for the action label

To provide a label for your custom action in all UI languages in Aprimo DAM, you have to create the corresponding translations in ADAM System, with these specifications:

For more information on how to create translations in ADAM System you can use the Help on this page link in the Translations area in ADAM System or go into ADAM Help > Administrator Guide > Configuration areas > Localization > Translations.

Code sample

The sample project provided here illustrates how the request and response mechanism works between an external application and Aprimo DAM PageHooks. It’s not at all meant to be useable as a real application, but gives you an idea how the different types of interaction work and can be handled.

The zip file contains a simple web application with a number of ashx web handler files, each giving a different response.

(The sample project will be available soon) 

Steps to test the sample project:

Install the sample web application on a web server

  1. Download the attached WebhookAPI.zip file
  2. Unzip the file then place the folder anywhere on a web server.
  3. Make sure that all files in the WebHookAPI folder are reachable from the Aprimo DAM environment, e.g. giving Everyone full access to the folder
  4. Open IIS Manager, right click Default Web Site in Sites folder and choose Add Application.
  5. Enter the following information:
    1. Alias: WebHookAPI
    2. Application pool: DefaultAppPool
    3. Physical path: <where the WebhookAPI folder is placed>.
  6. Click OK.
  7. Right click on the WebHookAPI site and choose Edit Permission. On the Security tab make sure that Everyone is added in “Group or user names”.

Make sure that HTTPS connections are enabled in your web server

For Microsoft IIS you can find more information in https://support.microsoft.com/en-us/help/324069/how-to-set-up-an-https-service-in-iis

Register the application in Aprimo MO, to get the necessary client ID.

See above for more information.

Create some custom actions in Aprimo DAM

Create a custom action in ADAM System (see (link) for more information on how to do this). Use the following specs to try out a few of the available examples:

  1. This action sends the request and just shows a “Success” flyout message in Aprimo DAM (response 200, no URL or message included).

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”Success”
       include=”auth-code”
       clientId=”[client id]”
       url=”https://YourServer/WebhookAPI/Success.ashx”
       location=”self”
/>

  1. This action sends the request, and redirects the user to the Assets home page in Aprimo DAM (response 200 + an internal URL).

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”SuccessWithRedirect”
       include=”auth-code”
       clientId=”[client id]”
       url=”https://YourServer/WebhookAPI/SuccessWithInternalURL.ashx”
       location=”self”
/>

 

  1. This action sends the request, and then opens an external website in a new window (www.aprimo.com) (response 200 + an external URL).

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”SuccessWithURLInNewWindow”
       include=”auth-code”
       clientId=”[client id]”
       url=”https://YourServer/WebhookAPI/SuccessWithExternalURL.ashx”
       location=”new”
/>

  1. This action sends the request but gets an error back, which is shown in a pop-up error message (Unauthorized: access is denied due to invalid credentials) (response 401).

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”Error401″
       include=”auth-code”
       clientId=”[client id]”
       url=”https://YourServer/WebhookAPI/Error401.ashx”
       location=”self”
/>

  1. This action sends the request but gets the response back too late, which results in a time-out message. The default max. allowed time to respond to PageHook requests is 15 seconds, but this value can be modified in the .pagehookActionTimeOut setting in ADAM System.

<add type=”Adam.Web.Extensions.Providers.Actions.PageHookAction, Adam.Web.Extensions”
       name=”Timeout”
       include=”auth-code”
       clientId=”[client id]”
       url=”https://YourServer/WebhookAPI/Timeout.ashx”
       location=”self”
/>

There are 10 other examples in total in the sample application, each with their own specs. Do try them out to get an idea of how Aprimo DAM handles these different situations.

Introduction

This shell script allows you to upload files from a folder to Aprimo DAM. The script can be executed manually or you could use a service such as the Windows Task Scheduler. This script is not executed in the Azure environment but runs on a local server.

The records created through the powershell script are immediately made available in Aprimo DAM: they do not have draft status.

For the upload, the script will use the MO REST API (for authentication) and the Aprimo DAM REST API.

Requirements

PowerShell 3 or higher

Use cases

You can use the shell script to upload files in bulk to Aprimo DAM. For instance, you could use it for a one-time bulk upload or for automatic uploads from a specific folder.

One-time bulk upload

In the situation where you have a folder containing a large number of assets in a (structured) folder, you don’t want to upload the files by hand. Instead, you can execute the script and let it run until all files are uploaded.

Note that files are uploaded one by one. If you need more parallelism, you will need to divide your files over multiple folders and run the script multiple times with different paths.

Folder watcher

You may want to monitor a folder and automatically upload any files or folders that are added to it. In that case, you can set up a scheduled task to run the shell script every hour (or more often, whatever is preferred). All files that are copied to the folder or any of the subfolders will be uploaded the next time the script runs. Note that your folder could also be a on a shared drive in your local network, which allows users to drop files in it.

Configuration

In order for the shell script to work, you have to add the Aprimo DAM url, MO client ID and authentication token to the app.config file.

The client ID and token must be set up in MO upfront. See See: https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module3 for more information.

Once you have the necessary information, you can fill out the app.config file:

<?xml version=”1.0″ encoding=”utf-8″?>
<configuration>
<appSettings>
<add key=”endpointUri” value=”http://yourcompany.dam.aprimo.com” />
<add key=”authorization” value=”Basic ZHV0Y2htZW46Y2E4KsIeK7KsaWIxNDhjZjg5MmZhZWQ4MmYwNjM5MzE=” />
<add key=”clientId” value=”F6ZSR71-H4OD” />
</appSettings>
</configuration>

Script execution

A sample call for the script:

Aprimo.HotFolderService.ps1 -Path C:\hotfolder -Classification 76f6824d83fc4c7d9440a8630103419c -ClassifySubFolders -ActionOnSuccess DeleteFile -FailedFilesFolder C:\failed

The Aprimo.HotFolderService.ps1 command accepts the following parameters:

How it works

The script works as follows: