Troubleshoot Adobe Experience Manager desktop app v1.x troubleshoot-aem-desktop-app

Troubleshoot the AEM desktop app to resolve the occasional issues related to installation, upgrade, configuration, and so on.

The Adobe Experience Manager desktop app includes utilities that assist you in mapping the AEM Assets repository as a network share on desktop (SMB share on macOS). Network share is an operating system technology that enables remote sources to be treated as if they were part of a computer’s local file system. For the desktop app, the remote file source is the digital asset management (DAM) repository structure of a remote AEM instance. The following diagram describes the desktop app topology:

With this architecture, the desktop app intercepts file system calls (open, close, read, write, and so on) to the mounted network share, and translates them into native AEM HTTP calls to the AEM server. Files are cached locally. For more details, see Use AEM desktop app v1.x.

AEM desktop app component overview desktop-app-component-overview

The desktop app includes the following components:

Intended use cases for the AEM desktop app intended-use-cases-for-aem-desktop-app

The AEM desktop app uses the network share technology to map a remote AEM repository to a local desktop. However, it is not intended as a replacement for a network share holding assets, where users perform digital asset management operations directly from their local desktop. These include moving or copying multiple files, or dragging large folder structures to the AEM Assets network share directly in Finder/Explorer.

The AEM desktop app provides a convenient way of accessing (opening) and editing (saving) DAM assets between the AEM Assets Touch UI and the local desktop. It links assets in the AEM Assets server with your desktop-based workflows.

The following example use case illustrates how AEM Desktop should be used:

This scenario is not the only use case. However, it illustrates how AEM Desktop is a convenient mechanism to access/edit assets locally. You are encouraged to use the DAM web UI as much as possible because it provides a better experience. It provides Adobe more flexibility to meet customer requirements.

Limitations limitations

WebDAV/SMB1 network share provides the convenience of working with files in an Explorer/Finder window. However, Explorer/Finder and AEM communicate over a network connection that has certain limitations. For example, the time consumed to copy a 1-GB file to the mounted WebDAV/SMB directory is approximately the same as the time required to upload a 1-GB file to a website using a web browser. In fact, in the former case, the duration may be longer due to inefficiencies of the WebDAV/SMB protocol and the OS’s WebDAV/SMB clients (particularly macOS X).

There are limitations to the types of tasks that can be performed from a mounted directory. In general, working with large files especially over a poor/high latency/low bandwidth network connection might be challenging, especially when editing large files.

Adobe recommends that you perform some use-case testing before committing to a client that certain types of files can be efficiently edited in-place from the mounted directory.

AEM Desktop is not suitable for performing intensive file system manipulation, including but not limited to:

Due to limitations in the operating system, Windows has a file size limitation of 4,294,967,295 bytes (approximately 4.29 GB). It is due to a registry setting that defines how large a file on a network share can be. The value of the registry setting is a DWORD with a maximum size that equals the referenced number.

The Experience Manager desktop app does not have a configurable timeout value that disconnects the connection between the Experience Manager server and the desktop app after a fixed time interval. When uploading large assets, if the connection gets timeout after a while, the app retries to upload the asset a few times by increasing the upload timeout. There is no recommended way to change the default timeout settings.

Caching and communication with AEM caching-and-communication-with-aem

The AEM desktop app provides internal caching and background upload capabilities to improve the end user experience. When you save a large file, it is first saved locally to let you continue working. After sometime (currently 30 seconds), the file is then sent to the AEM server in the background.

Unlike Creative Cloud Desktop or other file sync solutions, such as Microsoft One Drive, the AEM desktop app is not a full Desktop Sync client. The reason for this is that it provides access to the entire AEM Assets repository, which can be extremely large (hundreds of gigabytes or terabytes) for a full synchronization.

Caching provides the ability to limit the network/storage overhead to only a subset of assets that are relevant to the user.

Here is how the AEM desktop app performs caching:

Every operation is not cached locally. The following are transmitted to the AEM Server immediately without local caching:

Individual operations individual-operations

When troubleshooting sub-optimized performance for individual users, first review the app limitations. The subsequent sections include suggestions to improve performance for individual users.

Bandwidth recommendations bandwidth-recommendations

The bandwidth available to an individual user plays a critical role in the performance of the WebDAV/SMB client.

Adobe recommends that an individual user’s upload speed be close to 10 Mbps. For wireless connections, bandwidth is often shared between multiple users. If multiple users simultaneously perform tasks that consume network bandwidth, the performance can degrade even further. To avoid such issues, use a wired connection.

Concurrent operations concurrent-operations

When you interact with a file locally, AEM Desktop checks whether a newer version of the file is available in AEM. If a new version is available, the application downloads a fresh copy of the file to the local cache. However, AEM Desktop does not overwrite a locally cached file if it has been modified. This feature prevents your work from being overwritten inadvertently.

When the same file is modified both locally and in AEM, the locally modified version overwrites the version in AEM. In this case, the previous version is available in the asset’s timeline. You can verify both versions and resolve any conflicts.

If a local file is inconsistent with the version available in the server, the background upload status dialog notifies you about the conflict. To resolve the issue, open the conflicting file and save it. Saving the file forces AEM Desktop to sync your latest local changes to AEM. You can view previous versions of the asset in the timeline and resolve any conflicts.

Take into account additional factors when multiple users attempt to work in separate mounted directories targeting the same AEM instance. In particular, the following factors are important:

Additional AEM configurations additional-aem-configurations

If the WebDAV/SMB performance degrades drastically when multiple users work simultaneously, you can configure a few things in AEM, which can help improve performance.

Update Asset transient workflows update-asset-transient-workflows

You can improve AEM performance by enabling transient workflows for the DAM Update Asset workflow. Enabling transient workflows reduces the processing power required to update assets when they are created or modified in AEM.

Adjust Granite Transient Workflow queue adjust-granite-transient-workflow-queue

Another method for improving AEM performance is to configure the value of the maximum parallel jobs for the Granite Transient Workflow Queue job. The recommended value is roughly half the number of available CPUs with the server. To adjust the value, perform these steps:

AWS configuration aws-configuration

Owing to network bandwidth limitations, the performance of WebDAV/SMB may degrade when multiple users work simultaneously. Adobe recommends increasing the size of the AWS instance for a target AEM instance that runs on AWS to enhance the performance of WebDAV/SMB.

This measure specifically boosts the amount of network bandwidth available to the server. Here are some details:

Checked-out file limitations checked-out-file-limitations

There are a few known limitations in the way that you can interact with checked-out files through Explorer/Finder. If a file is checked out, it should be read-only to anyone except the user that has the file checked out. The implementation of the WebDAV/SMB1 protocol in AEM enforces this rule. However, OS WebDAV/SMB clients often don’t interact gracefully with checked-out files. Some oddities are described below.

General general

When writing to a checked-out file, the lock is only enforced within the AEM WebDAV implementation. Consequently, clients that use WebDAV, such as desktop app, only enforce the lock. The lock is not enforced through the AEM web interface. The AEM interface merely displays a lock icon in the card view for assets that are checked out. The icon is cosmetic and has no effect on the behavior of AEM.

In general, the WebDAV clients don’t always behave as expected. There may be additional issues. However, refreshing or checking the asset in AEM is a sound way to verify that an asset isn’t being modified. This behavior is typical of the OS WebDAV clients, which isn’t under Adobe’s control.

Windows windows

Deleting a file appears to succeed because the file disappears from the file explorer in Windows. However, refreshing the directory and checking in AEM Assets shows that the file is still present. In addition, editing files appears to succeed (no warning dialogs or error messages are displayed). However, reopening the file or checking in AEM Assets reveals that the file is unchanged.

macOS X mac-os-x

Replacing a file doesn’t display a warning or error, but checking the asset in AEM reveals that it remains unchanged. Refresh or check the asset in AEM to verify that it isn’t being modified.

Troubleshooting the desktop app icon issues (macOS X) troubleshooting-desktop-app-icon-issues-mac-os-x

After you install the desktop app, the desktop app menu icon appears in the menu bar. If the icon doesn’t appear, perform these steps to resolve the issue:

AEM Desktop attempts to sync any given file three times. If the file fails to sync after the third attempt, AEM Desktop considers the file to be in conflict and notifies you via the background upload status window. A conflict state indicates that your latest changes are still available to you locally, but they are not synced back to AEM. The AEM desktop app no longer attempts to sync.

The simplest way to fix this situation is to open the conflicting file and save it again. It forces AEM Desktop to attempt synchronization for an additional three occasions. If the file still fails to sync, see the sections below for more help.

Clearing AEM Desktop cache clearing-aem-desktop-cache

Clearing AEM Desktop’s cache is a preliminary troubleshooting task that can resolve several AEM Desktop issues.

You can clear the cache by deleting the application’s cache directory at the following locations.
In Windows, %LocalAppData%\Adobe\AssetsCompanion\Cache\

In Mac, ~/Library/Group/Containers/group.com.adobe.aem.desktop/cache/

However, the location can change depending on AEM Desktop’s configured AEM endpoint. The value is an encoded version of the targeted URL. For example, if the application is targeting http://localhost:4502, the directory name is http%3A%2F%2Flocalhost%3A4502%2F.

To clear the cache, delete the <Encoded AEM Endpoint> directory.

Finding the AEM Desktop version finding-the-aem-desktop-version

The procedure to ascertain the AEM Desktop version is the same for both Windows and macOS.

Click the AEM Desktop icon, and then choose About. The version number is displayed on the screen.

Upgrading the AEM desktop app on macOS upgrading-aem-desktop-app-on-macos

Occasionally, issues may occur when upgrading the AEM desktop app on macOS. Legacy system folders for the AEM desktop app cause these issues. It prevents new versions of AEM Desktop to load correctly. To remedy this issue, the following folders and files can be manually removed.

Prior to executing the steps below, drag the “Adobe Experience Manager Desktop” application from the macOS Applications folder to the Trash. Then open the terminal, and execute the following command, providing your password when prompted.

sudo rm -rf ~/Library/Application\ Support/com.adobe.aem.desktop
sudo rm -rf ~/Library/Preferences/com.adobe.aem.desktop.plist
sudo rm -rf ~/Library/Logs/Adobe\ Experience\ Manager\ Desktop

sudo find /var/folders -type d -name "com.adobe.aem.desktop" | xargs rm -rf
sudo find /var/folders -type d -name "com.adobe.aem.desktop.finderintegration-plugin" | xargs rm -rf

Saving a file checked out by others saving-a-file-checked-out-by-others

Technical limitations of the operating system prevent users from having a consistent experience when attempting to overwrite a file that others have checked out. The experience varies depending on the application used to edit the checked out file. Sometimes, the application displays an error message indicating a disk write failure or displays a seemingly unrelated or generic error. On other occasions, no error message is displayed and the operation appears to succeed.

In this case, closing and reopening the file may reveal that the contents are unchanged. However, some applications may store a backup of the file so your changes can be applied.

Regardless of the behavior, the file remains unchanged when you check it in. Even if a different version of the file is displayed, the changes are not synced to AEM.

Troubleshooting problems around moving files troubleshooting-problems-around-moving-files

The server API requires additional headers, X-Destination, X-Depth, and X-Overwrite, to be passed for the move and copy operations to work. The Dispatcher does not pass these headers by default, which causes these operations to fail. For more information, see Connecting to AEM Behind a Dispatcher.

Troubleshooting AEM Desktop connection issues troubleshooting-aem-desktop-connection-issues

SAML redirect issue saml-redirect-issue

The most common reason for issues with AEM Desktop connecting to your SSO-enabled (SAML) AEM instance is that the SAML process does not redirect back to the originally requested path. Alternatively, the connection may be redirected to a host that is not configured in the AEM desktop app. Perform these steps to verify the login process:

SSL configuration issue ssl-configuration-issue

The libraries that the AEM desktop app uses for HTTP communication uses strict SSL enforcement. At times, a connection may succeed using a browser but fails to use the AEM desktop app. To configure SSL appropriately, install the missing intermediate certificate in Apache. See How to install an Intermediate CA cert in Apache.

Using AEM Desktop with Dispatcher using-aem-desktop-with-dispatcher

AEM Desktop works with AEM deployments behind a Dispatcher, which is a default and recommended configuration for AEM servers. AEM dispatchers in front of AEM authoring environments are typically configured to skip caching DAM assets. Therefore, dispatchers do not provide additional caching from the AEM Desktop standpoint. Ensure that the Dispatcher configuration is adjusted to work for AEM Desktop. For additional details, see Connecting to AEM with a Dispatcher.

Checking for log files checking-for-log-files

Depending upon your operating system, you can find the log files for AEM Desktop at the following locations: