Configuring Regex for Valid File Name Characters in AEM Guides

Introduction

File names in Adobe Experience Manager (AEM) Sites play a crucial role in maintaining the integrity of URLs and ensuring smooth navigation across digital experiences. With the release of AEM Guides 3.8, administrators gained the ability to define a custom list of valid characters for file names, thereby preventing issues caused by special characters in URLs. This blog post explores how to configure regex for valid file name characters, ensuring seamless operation within AEM.

Problem Statement or Background

In previous versions of AEM, file names could include special characters such as @, $, >, and more. While seemingly harmless, these characters could create significant problems when used in URLs. Issues often arose when attempting to open topics from the DITA Map Dashboard or clicking on topic links in the Table of Contents (TOC). The presence of certain special characters in the URL led to broken links or pages failing to open, disrupting the user experience.

With the introduction of AEM Guides 3.8, administrators now have the power to enforce specific rules on file naming conventions. By configuring a regex pattern for valid file name characters, administrators can ensure that only allowed characters are used, reducing the risk of URL-related issues.

Key Concepts or Terminology

Regex (Regular Expression): A sequence of characters that define a search pattern. In the context of file names, regex is used to specify which characters are permitted.

Special Characters: Characters that are not alphanumeric and are often reserved for specific functions in URLs. Examples include @, $, >, *, :, and others.

AEM Guides: Adobe Experience Manager Guides, a component of AEM that provides advanced content management capabilities for structured content, such as DITA (Darwin Information Typing Architecture).

Detailed Explanation

In AEM Guides 3.8, the default configuration for valid file name characters includes the following pattern: a-z A-Z 0-9 - _. This pattern allows lowercase and uppercase letters, numbers, hyphens, and underscores in file names. If no changes are made to the configuration, any special characters included in a file’s title will be automatically replaced with a hyphen - in the file name.

For instance, a file titled “Introduction 1” or “Introduction@1” will both result in the file name “Introduction-1”. This ensures consistency and prevents issues with URLs containing unsupported characters.

However, AEM administrators may need to extend this list of valid characters to accommodate specific requirements. The process involves modifying the regex pattern in the AEM Web Console Configuration page.

Step by Step Guide

1. Access the Configuration Page:
   • Open the Adobe Experience Manager Web Console Configuration page. Typically, this can be accessed through the following URL: http://<server name>:<port>/system/console/configMgr.
2. Locate the Relevant Bundle:
   • Use the search function to find the com.adobe.fmdita.config.ConfigManager bundle. This bundle contains the configuration settings for file name validation.
3. Modify the Regex Pattern:
   • In the “Regex for Valid Characters” property, ensure that the basic pattern [-a-zA-Z0-9_] is included. This pattern allows hyphens, letters, numbers, and underscores. If additional characters need to be permitted, they can be added to this list.
   • Important Note: The list must always start with a hyphen - to maintain proper functionality. Additionally, certain characters such as */:[\]|#%{}?&<>"/+ are automatically replaced with a hyphen, regardless of the regex configuration.
4. Save the Configuration:
   • After making the necessary adjustments, click “Save” to apply the changes. The new regex pattern will now govern the creation of file names within AEM Guides.

Best Practices or Tips

• Consistency is Key: Stick to a simple and consistent file naming convention to avoid confusion and ensure compatibility across different systems.
• Test Your Configuration: After modifying the regex pattern, test the creation of files with various titles to ensure the expected behavior.
• Keep It Simple: Avoid overcomplicating the regex pattern. The default configuration is sufficient for most use cases, and excessive customization may introduce unforeseen issues.

Case Studies or Examples

Consider a scenario where an organization needs to allow additional special characters in file names, such as & and +. By modifying the regex pattern to include these characters, the organization can meet its unique requirements without sacrificing the integrity of its URLs.

For example, if the regex pattern is updated to [-a-zA-Z0-9_&+], a file titled “Project & Plan+1” would result in the file name “Project-&-Plan+1”. This custom configuration ensures that the file name remains valid while preserving the intended special characters.

Troubleshooting and FAQ

Q: What happens if I forget to configure the regex pattern after upgrading to AEM Guides 3.8? A: If the valid special characters list is not configured, the file creation process may produce unexpected results, such as invalid URLs or file names that do not meet your organization’s standards.

Q: Can I use special characters in folder names as well? A: No, the regex pattern configured in the “Regex for Valid Characters” property applies only to file names, not folder names.

Q: What should I do if a specific character is causing issues? A: If a particular character is problematic, consider removing it from the regex pattern or replacing it with a hyphen -.

Conclusion

Configuring a regex pattern for valid file name characters in AEM Guides is a critical step in ensuring that your digital content is accessible, navigable, and free from URL-related issues. By following the steps outlined in this guide, AEM administrators can customize their file naming conventions to meet the specific needs of their organization while maintaining the integrity of their digital experiences.