|
| 1 | +# Umbraco.Cms.Integrations.DAM.Aprimo |
| 2 | + |
| 3 | +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 with a value converter providing a strongly typed model for rendering, as well as a sample rendering component. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +Requires minimum versions of Umbraco CMS: |
| 8 | +- CMS: 10.3.0 |
| 9 | + |
| 10 | +## How To Use |
| 11 | + |
| 12 | +### Configuration |
| 13 | + |
| 14 | +The following configuration is required to connect to the _Aprimo_ DAM workspace: |
| 15 | + |
| 16 | +``` |
| 17 | +{ |
| 18 | + "Umbraco": { |
| 19 | + "CMS": { |
| 20 | + "Integrations": { |
| 21 | + "DAM": { |
| 22 | + "Aprimo": { |
| 23 | + "Settings": { |
| 24 | + "Tenant": "[your_tenant_name]" |
| 25 | + }, |
| 26 | + "OAuthSettings": { |
| 27 | + "ClientId": "[your_aprimo_client_id]", |
| 28 | + "ClientSecret": "[your_aprimo_client_secret]", |
| 29 | + "RedirectUri": "https://[your_website_base_url]/umbraco/api/aprimoauthorization/oauth", |
| 30 | + "Scopes": "api offline_access" |
| 31 | + } |
| 32 | + } |
| 33 | + } |
| 34 | + } |
| 35 | + } |
| 36 | + } |
| 37 | +} |
| 38 | +``` |
| 39 | + |
| 40 | +The configuration is split in two components: a generic one that holds your tenant name, and one for OAuth settings. |
| 41 | + |
| 42 | +The authorization process is managed using the [OAuth flow - Authorization Code with PKCE](https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module7), meaning that when making a request for an access token, you will need to generate a code verifier and a code challenge. |
| 43 | + |
| 44 | +`Client Id` and `Client Secret` details are retrieved from your [Aprimo Client Registration](https://developers.aprimo.com/marketing-operations/rest-api/authorization/#module2), which you will need to set up with the redirect URI pointing to the [`AprimoAuthorizationController`](https://github.com/umbraco/Umbraco.Cms.Integrations/blob/feature/aprimo-integration/src/Umbraco.Cms.Integrations.DAM.Aprimo/Controllers/AprimoAuthorizationController.cs) - `OAuth` action. |
| 45 | + |
| 46 | +Using the `offline_access` scope, the response from Aprimo API will contain besides an access token, a refresh token, with an expiration period of 10 days, that will keep the API access valid. |
| 47 | + |
| 48 | +### Backoffice usage |
| 49 | +To use the media picker, a new data type should be created based on the `Aprimo Media Picker` property editor. |
| 50 | + |
| 51 | +If the configuration is not valid, an error tag will be displayed in the right upper corner of the configuration box. |
| 52 | + |
| 53 | +Otherwise, you will be able to select one of the two available options for picking assets: |
| 54 | +- Aprimo API - items are retrieved using the API and an overlay of the property editor will display the list of available items in the DAM workspace. |
| 55 | +- Aprimo Content Selector - rich UI tool hosted on Aprimo Cloud where you can pick items using a familiar Aprimo interface. |
| 56 | + |
| 57 | +#### Browser information |
| 58 | +Before using the integration with Aprimo, please make sure to use a browser that is supported by Aprimo Cloud, in contrary you will not be able to authenticate, nor use the Content Selector. |
| 59 | + |
| 60 | +Aprimo currently supports these browsers, but make sure to check [this](https://help.aprimo.com/Content/Marketing_Operations_Help/aprimo_basics/browsers_configuring_concept.html) topic for an updated list: |
| 61 | +- Chrome for Windows and Macintosh |
| 62 | +- Edge (Windows 10 only) |
| 63 | +- Internet Explorer 9, 10, and 11 |
| 64 | +- Safari 6, 6.1, 6.2, and 7.0 (Macintosh only) |
| 65 | + |
| 66 | +### Front-end rendering |
| 67 | +A strongly-typed model will be generated by the property value converter and an HTML helper is available to easily render the asset on the front-end. |
| 68 | + |
| 69 | +Make sure your template has a reference to the following using statement: |
| 70 | +`@using Umbraco.Cms.Integrations.DAM.Aprimo.Helpers;` |
| 71 | + |
| 72 | +And render the media asset (assuming a property based on the created data type with alias `AprimoMediaPicker` has been created): |
| 73 | +`@Html.RenderAprimoAsset(Model.AprimoMediaPicker)`. |
| 74 | + |
| 75 | +Properties available from the strongly-typed model: |
| 76 | +- Title |
| 77 | +- Thumbnail |
| 78 | +- Crops |
| 79 | +- Asset fields |
0 commit comments