DAM Common Integration Patterns
The integration patterns outlined in this tutorial are only for Aprimo DAM.
Some of the common integration patterns below, we have a collections in our API Reference that can be used to assist in learning.
Before you begin developing, read about Aprimo Rate Limiting.
Selection Aprimo Content
One of the first steps in any downstream integration with Aprimo DAM will be the process of selecting content. If the integration requires a UI experience where users can manually select an asset, crop, or rendition then Aprimo recommends the use of Content Selector or Aprimo Quick Connect, depending on the capabilities of the platform being integrated to. Content Selector and Quick Connect are often used for integrations to CMS or Email systems. If the integration requires selecting a specific asset or searching for a set of assets via a backend call then the Aprimo REST API is the recommended solution. Aprimo REST API is used for integrations to platforms like Rights Management, ERP, and others.
REST API
Using the REST API for selecting Aprimo content will return a json object containing information about the asset. If a record ID is already known, then an API request can be made to /records/{{recordID}}.
curl --location 'https://{{domain}}.dam.aprimo.com/api/core/record/{{recordId}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'API-VERSION: 1' \
--header 'Accept: application/json'
An example request can be found in the POSTMAN collection titled “Get Single Record”.
Aprimo also supports Aprimo Select Headers which can be used to return additional information on the records. If Aprimo CDN is enabled and there are assets that have been cached in the CDN, then select headers can be used to get the current public URIs of assets cached in the CDN. See POSTMAN request titled “Get Single Record Publicuris.”
If no record ID is used then using the /records/search endpoint is recommended.
curl --location 'https://{{domain}}.dam.aprimo.com/api/core/search/records' \
--header 'Authorization: Bearer {{token}}' \
--header 'API-VERSION: 1' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"searchExpression":
{
"disabledKeywords": null,
"supportWildcards": false,
"defaultLogicalOperator": "AND",
"languages": ["c2bd4f9bbb954bcb80c31e924c9c26dc"],
"expression": "Title CONTAINS '\''umbrella'\''",
"parameters": [],
"namedParameters": {},
"subExpressions": null
},
"logRequest": true
}'
This endpoint allows for a search expression to be used to filter assets. This option is recommended when the use case calls for pulling in many Aprimo assets into the connecting system, or when there is an identifiable common trait between all assets that are needed for the use case.
To learn more about searching for record and search expressions. Check out our Searching article.
Content Selector
Aprimo Content Selector will launch an Aprimo made UI allowing users to select 1 or more assets to be returned to the application that launched Content Selector and is the recommended tool for connecting to CMS, ERP, or Commerce systems that support it. The json object returned, as well as configuration options, can be viewed in the Content Selector documentation. Content Selector features its own authentication and will prompt the user to login to their Aprimo user before allowing them to browse Aprimo; this also ensures users browse Aprimo using their personal permissions. Content Selector can be configured to work with the Aprimo CDN, and in doing so will only show assets that have been cached on the public CDN. The returned json object will contain the record ID as well as the public URI.
Retrieving Aprimo Content
The 2nd step to the typical Aprimo integration is retrieving your selected content from Aprimo. There are 3 primary ways of accomplishing this. Aprimo Public CDN, Asynchronous Download Orders, and Synchronous Download Orders. For CMS, Email Systems, or Commerce systems the Aprimo Public CDN is the recommended option as it is always synchronous and allows for a range of transformations supported by Fastly. If a system can’t accept public uris and instead needs the actual file then the integration will use either Synchronous Download Order, Asynchronous Download Orders, or a combination of both. Asynchronous Orders are capable of doing Aprimo transformations, such as cropping, on assets that are ordered. Synchronous Download Orders are made synchronous by bypassing the Aprimo transformation process. Both Aprimo Public CDN order and Aprimo Download Orders are placed using the Aprimo REST APIs order endpoint.
Aprimo Public CDN
The Aprimo Public CDN approach is best used when all assets should be publicly available, such as with a live website. Whether an asset has been cached in the Aprimo Public CDN or not, the url will be immediately available. The public url is immediately available because the public url pattern is configured in a global Aprimo setting; even if the asset hasn’t been cached yet, Aprimo knows the url it will be hosted at. Assets can also be cached automatically according to Aprimo DAM rules. E.G. when an asset is created, added to a specific classification, or some metadata is set. Using the CDN method also gives access to all asset transformations that Fastly supports.
Asynchronous vs Synchronous Download Orders
Asynchronous and Synchronous download orders are ideal for any system that can not accept a public uri and instead needs the file itself, such as social media, Sharepoint, etc. The difference between the two is that asynchronous allows your request for a download url to also request a transformation to the asset. All Aprimo supported transformations can be found in the download order training documentation. If no transformation is selected in the order, and the target is the master file, then the order will return synchronously.
The XML Writeback feature must also be disabled. As this counts as a transformation.
Keeping Content Up To Date
Any integration with Aprimo will likely require the ability to keep content up to date; whether this is updating content in Aprimo or updating content outside of Aprimo there are a few ways to tackle this use case. If your integration needs to update content within Aprimo the Aprimo REST API will be the recommended option. To update content outside of Aprimo making use of Aprimo DAM rules is the best option. These rules follow a set of configurable conditions, and when those conditions are met then actions will occur, such as sending an HTTP request to an integration with data.
Updating Aprimo Objects Using REST API
If your integration needs to update Aprimo records, classifications, files, or other objects the Aprimo REST API will be what your integration uses. A common use is a CMS integration that sends updates to the Aprimo asset’s metadata containing usage stats about the asset or the specific pages that the asset is used on.
Make a PUT request to /record/{{recordID}}
curl --location --request PUT 'https://{{domain}}.dam.aprimo.com/api/core/record/{{recordID}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'API-VERSION: 1' \
--header 'Content-Type: application/json' \
--data '{
"fields":{
"addOrUpdate":[
{
"id":"{{fieldID-Numeric}}",
"localizedValues":[
{
"languageId":"c2bd4f9b-bb95-4bcb-80c3-1e924c9c26dc",
"values": [
"2dd66657db834b579a12a96c00ed6522",
"023efc73cf4b43dbb18aa83900f77c54"
]
}
]
}
]
}
}'
The example above is using a request body specific to the User List metadata data type. The API Reference contains examples for all other metadata data types.
Expiring Aprimo Content
In many integrations content will need to be expired and downstream systems will need to be informed that the content can no longer be used, has to be updated, or similar. Aprimo handles this using the Aprimo DAM Rules pattern. This use case applies to most types of downstream integrations.
DAM Rules
If the integration needs to inform an external system that Aprimo content is no longer able to be used, then using the DAM rules is the recommended solution. Aprimo DAM rules allow your integration to make HTTP requests that can contain data such as a message stating the content no longer has the legal rights to be used.
Tracking Aprimo Content
Once content has left Aprimo and is being published publicly it is often useful to have exposure of where that content is being used. Aprimo recommends when content is published or used outside of Aprimo that the Aprimo record is updated to include information about its use. If published publicly in a CMS the Aprimo record should contain the url that the content was published at. If the content is used in Rights Management, Email Systems, PIMs, or other systems, the Aprimo record should be updated to include what systems it is being used in. The Aprimo REST API is the best solution for this use case. When your integration processes an Aprimo asset to an external system the integration should make a request to update the Aprimo record.
REST API
If content is used outside of Aprimo, like in a CMS, the integration should use the Aprimo REST API to update the Aprimo content’s metadata to include information about its use. For CMS’s this should include urls to the publically available webpages the content can be found at.
To update a record to include a hyperlink to where the content is published, use the following request
curl --location --request PUT 'https://{{domain}}.dam.aprimo.com/api/core/record/{{recordID}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'API-VERSION: 1' \
--header 'Content-Type: application/json' \
--data '{
"fields":{
"addOrUpdate":[
{
"id":"{{fieldID-Hyperlinks}}",
"localizedValues":[
{
"languageId":"c2bd4f9b-bb95-4bcb-80c3-1e924c9c26dc",
"hyperlinks": [
{
"url":"www.aprimo.com",
"displayText": "Aprimo Website"
}
]
}
]
}
]
}
}'
The above request will add a new link to a hyperlink metadata field.
For Rights Management, Email Systems, PIMs, or other systems a better solution may be updating a ClassificationList field in Aprimo, where you have a specific classification for each integration you have.
curl --location --request PUT 'https://{{domain}}.dam.aprimo.com/api/core/record/{{recordID}}' \
--header 'Authorization: Bearer {{token}}' \
--header 'API-VERSION: 1' \
--header 'Content-Type: application/json' \
--data '{
"fields":{
"addOrUpdate":[
{
"id":"{{fieldID-ClassificationList}}",
"localizedValues":[
{
"languageId":"c2bd4f9b-bb95-4bcb-80c3-1e924c9c26dc",
"values":[
"{{integrationClassifcation1}}",
"{{integrationClassification2}}"
]
}
]
}
]
}
}'
In the above request you would have a unique classification for each of your integrations, and when an asset is uploaded to an external system by that integration, you note that occurance by updating the ClassifcationList field.
Caching Aprimo Content
When creating an integration with Aprimo its important to cache Aprimo data so your integration can retrieve data from Aprimo without always relying on HTTP requests. There are 2 main caching patterns for this and each pattern is best suited to different use cases. If your use case involves browsing Aprimo assets then the On-Demand pattern is best suited to the use case. If your use case involved using Aprimo data in aggregation or creating content that derives from Aprimo data then the Proactive pattern would best suit your use case.
On-Demand Caching
The On-Demand caching pattern will store Aprimo REST API results locally, and then reference those local versions until they become stale. If your use case involves browsing Aprimo assets, or just working with a single Aprimo asset, then On-Demand is the recommended pattern to use. Typically data can be configured to be considered stale after 10 minutes, but this may differ depending on your organization. After the results have become stale, make the HTTP request to Aprimo to get fresh data.
Proactive Caching
Proactive Caching involves making use of Aprimo DAM Rules and Aprimo Productivity Webhooks which will allows Aprimo to notify your integration of changes that occur in Aprimo. The Proactive Cache is best suited for use cases where your integration will be aggregating data from Aprimo or creating new content out of Aprimo data. This includes integrations that display a carousel of Aprimo images, or aggregate usage stats to display them in a graph. Your integration will store a local copy of Aprimo data and update it as Aprimo sends updates to the integration.