Set up AEM Assets

Experience Workspace allows authors to add assets by uploading them directly to the document as well as a full integration with AEM Assets. The AEM Assets integration provides an out-of-the-box way to work with your assets in AEM Assets. It also allows you to use the Experience Workspace App SDK to build rich applications that leverage any content stored on your AEM as a Cloud Service instance.

This document describes how to set up AEM Assets for your site.

Configuring the AEM Assets integration

To set up the AEM Assets integration you need to fulfill these prerequisites:

You have AEMaaCS with either a publish instance or Dynamic Media.
You have permissions to change configurations in Cloud Manager.
You have permissions change configurations in Experience Workspace.

Once these prerequisites are fulfilled, you can configure the integration in two steps:

Configure the AEM as a Cloud Service side
Configure the Experience Workspace side

Step 1 - Configure AEM as a Cloud Service

You need to set an environment variable within Cloud Manager for your AEM as a Cloud Service environment.

Open Cloud Manager for your AEM as a Cloud Service environment and add an environment variable with the following values.

Field	Value
Name	`ADOBE_PROVIDED_CLIENT_ID`
Value	`darkalley`
Step Applied	`All`
Type	`Normal`

Expect a full restart (~10-20 minutes) when this environment variable is saved. For details on how to use Cloud Manager to set environment variables, please see the document Environment variables in Cloud Manager.

Step 2 - Configure Experience Workspace

Open the configuration of your site by navigating to the site root in the content browser and then clicking the gears icon at the end of the breadcrumbs. Then add the following configuration keys to the data sheet of your config.

Key	Required	Values	Description
`aem.repositoryId`	Yes	`author-pXXXX-eYYYY.adobeaemcloud.com` or `delivery-pXXXX-eYYYY.adobeaemcloud.com`	Determines the repository mode. The prefix (`author-` / `delivery-`) controls which mode is active.
`aem.assets.prod.origin`	No	e.g. `production-domain.com`	Overrides the auto-derived asset URL origin. If the value starts with `delivery-`, DM delivery mode is also activated.
`aem.assets.prod.basepath`	No	e.g. `/adobe/assets`	Overrides the default base path (`/adobe/assets`) used in DM and delivery URLs.
`aem.assets.image.type`	No	`link`	Insert images as links instead of image tags. Useful for Dynamic Media URLs that need to bypass Media Bus.
`aem.asset.dm.delivery`	No	`on`	Use author for browsing, but construct DM delivery URLs when inserting. Activates Author+DM mode.
`aem.asset.smartcrop.select`	No	`on`	Show the Smart Crop selection dialog when an image is selected. Implies DM delivery.
`aem.asset.mime.renditions`	No	e.g. `image/vnd.adobe.photoshop:avif, video/*:original`	Comma-separated `mimetype:renditiontype` pairs that override the default rendition type. Supports exact types and prefix wildcards (`image/`, `video/`). Defaults: images → avif, videos → /play, others → original.

All keys are set in the site config. Site-level values take precedence over org-level values.

Use the integration

Once the configuration is done in both AEM as a Cloud Service and Experience Workspace, authors can use it to select assets from AEM Assets into documents in Experience Workspace.

Open any page and notice you have a new image icon in your toolbar. This will open a modal dialog to your AEM Assets. For details on how to author with media, please see the document Adding media.

Troubleshooting

Here are some common issues when using the AEM Assets integration and how to solve them.

The assets pane opens in Experience Workspace, but contains an error.

Make sure you have waited 5-10 minutes after Cloud Manager tells you the variable is saved on your instance.
Make sure the org you are logged into in Experience Workspace is the same org that is allowed in AEM.

When I select an image, it is broken in Experience Workspace.

Ensure that you have a publish server configured (author only is not supported).
Ensure that the asset is published.

I don't see any folders in the asset picker.

Check if your configuration points to a Dynamic Media instance (these do not support folders).
You can use an author hostname + aem.asset.dm.delivery to browse your assets hierarchy, but use Dynamic Media URLs for delivery.

Dynamic Media recommendations

Dynamic Media provides several capabilities you may want to leverage for your project. This could be Smart Crop, image presets, asset transformations via URL manipulation, or even asset management in general. However, Edge Delivery itself provides a scalable, low complexity, and performant image optimization service called Media Bus.

If you require the Dynamic Media features listed above, we recommend using Dynamic Media URLs during authoring and allowing Media Bus to optimize the images for final delivery. This creates a flexible and performant solution that leverages both technologies with the following advantages.

Asset management - Authors who are familiar with AEM Assets and prefer this environment for managing assets can continue to do so while still leveraging the performance benefits of Edge Delivery Services.
URL-based asset transformations - Configured in AEM or Experience Workspace and baked into an immutable Media Bus image prevents bad actors from manipulating images in real-time on your live website.
Smart Crop - Experience Workspace allows selection of Smart Crop and AEM-made renditions.
Real-time image replacements - It can be enticing to want to swap live images in real-time on your live website. When done at scale, even an asset with minor changes in size, format, and color can create undesired results without proper QA. In leveraging the preview / publish model of Edge Delivery, quality checks can be performed on the affected pages before going live.
Image delivery optimization - Media Bus supports all modern image formats: AVIF, SVG, WEBP, and more. With modern browsers and evergreen update mechanisms, it is no longer required to sniff user agents to determine what formats a browser supports.

Using Dynamic Media directly on your site

There may be times where it is advantageous to use Dynamic Media directly on your site. Product imagery is one such use case. These scenarios are best handled by creating images during block decoration and not through manual authoring.

If you find a scenario where you need to create Dynamic Media content that funnels through authoring and onto the final page, please note the following:

In order to bypass Media Bus ingestion, you treat images as links. These links will be delivered as anchor tags and a developer can "hydrate" them into picture / image tags.
Please determine a pattern / convention with your content creators to account for conveying alt text information.
Placing Dynamic Media links in performance sensitive sections of your page will need to be accounted for. This includes using the same domain for DM as you would your site and ensuring headers have proper cache information.

Swapping existing assets

Authors may need to update an existing asset without having to change every page on which the asset is currently used. Follow these steps in such cases.

On da.live, use the side navigation panel to navigate to your assets using the "files" icon.
In Adobe Experience Manager Assets, navigate to the folder that contains the asset you want to replace.
Replace the asset and re-publish it.
Navigate to a page in Experience Workspace that uses the asset in question.
Once you can see your changes reflected, Edge Delivery is ready to ingest it. Copy the asset URL.
Paste the asset publish URL into Experience Workspace's search. This will list every page on Experience Workspace that is using the asset.
Use the share button (action bar > share icon) to copy the AEM URLs.
Paste the URLs into Experience Workspace's bulk preview & publish tool. Run a preview on these URLs.
QA your content to ensure all pages changed in the way you expect.
Once pages have passed QA, publish them.