> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AEM Integration: Advanced Configurations

> Fine-tune how Gradial connects to AEM — custom authentication scopes, multi-site configurations, and environment-specific settings.

This guide covers the advanced configuration options available in your AEM integration settings. These configurations allow you to fine-tune how Gradial connects to and interacts with your AEM instance.

## Accessing Integration Settings

1. Navigate to **Settings** in your organization
2. Select **Integrations** from the sidebar
3. Click on your **AEM Integration**
4. Use the tabs at the top to navigate between configuration sections

***

## General Settings

The General tab contains core configuration options for your AEM integration.

### Integration URL

The AEM service endpoint URL for this integration. This is the base URL Gradial uses to communicate with your AEM instance.

**Example:** `https://aem-sandbox.gradial.com`

### Mark as Production Instance

Toggle this option to designate your AEM environment as a production instance. When enabled:

* Additional safeguards are applied to prevent accidental changes
* Workflow approvals may be enforced
* Audit logging is enhanced

### Authoring Domain Override

Use this field when your AEM editing environment uses a different URL than the service endpoint.

**Example:** `https://author.example.com`

**When to use:**

* Your AEM author instance is on a different domain than the publish instance
* You have separate authoring and preview environments

### Workflow Type

Choose how content changes are applied to your AEM instance:

| Workflow Type   | Description                                                                                                | Best For                                            |
| :-------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
| **Launch**      | Creates new content using AEM Launches workflow. Changes are staged and can be reviewed before publishing. | Production environments, content requiring approval |
| **Direct Edit** | Edits existing pages directly without launches. Changes are applied immediately.                           | Development environments, quick updates             |

### MSM Inheritance Protection

**Block edits to pages with active MSM inheritance** (Recommended)

When enabled, Gradial will prevent modifications to pages that are managed through AEM's Multi Site Manager (MSM) inheritance. This protects your content governance model by ensuring inherited content isn't accidentally modified.

**Default:** Enabled

***

## Networking

The Networking tab provides options for network configuration and rate limiting.

### Advanced: Network & Proxy Settings

Expand this section to configure:

* Custom proxy servers
* Network timeouts
* SSL/TLS certificate handling
* Custom headers for authentication

### Rate Limiting

Control the frequency of API requests to your AEM instance.

**Enable rate limiting for this connection**

When enabled, you can configure:

* Maximum requests per second
* Burst limits
* Queue behavior for exceeded requests

**Default:** Disabled (uses default resilience settings)

**When to enable:**

* Your AEM instance has strict rate limits
* You're experiencing throttling from AEM
* You need to share capacity with other integrations

***

## Asset Sync (Journaling)

Gradial can keep its asset index in sync with AEM using Adobe's **I/O Events Journaling API**. Without journaling, changes in AEM (new, updated, or deleted assets) are only picked up during periodic full re-scans, which are slow and expensive for large asset libraries. With journaling enabled, Gradial polls a stream of change events from Adobe and applies them incrementally — so asset changes show up in Gradial search within minutes instead of waiting for the next full re-scan.

A scheduled full reconciliation still runs periodically as a safety net.

<Info>
  Journaling-based asset sync must be enabled for your organization. Contact your Gradial team to get access. If journaling is not configured, asset sync continues to work through the existing scheduled re-scans — there is no disruption for integrations that haven't set it up.
</Info>

### Prerequisites

You'll need an Adobe Developer Console project with an AEM Assets event registration. From that project, gather three values:

| Value                              | Where to find it                                                      |
| :--------------------------------- | :-------------------------------------------------------------------- |
| **Journaling Unique API Endpoint** | Under the **Journaling** section of your Adobe I/O event registration |
| **Client ID**                      | From the project's **OAuth Server-to-Server** credentials             |
| **Client Secret**                  | From the same credentials page                                        |

### Configuring journaling

Journaling details can be added in two places:

* **AEM onboarding wizard** — when setting up a new AEM integration
* **Integration configuration modal** — for an existing AEM integration, under your integration settings

Enter the Journaling Unique API Endpoint, Client ID, and Client Secret from your Adobe Developer Console project. Once configured, Gradial handles authentication and polling automatically.

***

## Mappings

The Mappings tab configures content paths and templates for your AEM integration.

### Default Experience Fragment Template

Specifies the template used when creating new Experience Fragments.

**Format:** Must start with `/conf/`

**Example:**

```
/conf/wknd/settings/wcm/templates/xf-web-variation
```

**When to configure:**

* You want a consistent template across all XF creations
* To avoid specifying the template every time you create an XF

> **Note:** This is optional. If not set, you'll need to specify the template when creating Experience Fragments.

### Experience Fragment Paths

Define the parent folders where Experience Fragments can be created. AI agents will intelligently select the most appropriate path based on content type and context.

**Format:** Each path must start with `/content/experience-fragments/`

**Examples:**

```
/content/experience-fragments/site/heroes
/content/experience-fragments/site/promos
/content/experience-fragments/site/global
```

**Adding paths:**

1. Enter a path in the input field
2. Click **+ Add** or press **Enter**
3. Repeat for additional paths

**Path Selection Logic:** When multiple paths are configured, the agent:

1. Analyzes the content being created
2. Matches it to the most semantically appropriate path
3. Uses the first path as a fallback if no better match is found

**Best Practices:**

* Use semantic folder names (e.g., `/heroes` not `/folder1`)
* Organize by content type or channel
* Add paths in order of preference (first path is the fallback)

> 📖 For detailed Experience Fragment configuration, see: [Configuring Experience Fragment Defaults](https://www.notion.so/Configuring-Experience-Fragment-Defaults-2e37521d682e813ba989c83c16cd4303)

### Page Mappings

Configure content path mappings for AEM site and DAM operations.

| Field                | Description                  | Example                     |
| :------------------- | :--------------------------- | :-------------------------- |
| **Site Path**        | The content path in AEM      | `/content/gradial-core`     |
| **DAM Path**         | Corresponding DAM asset path | `/content/dam/gradial-core` |
| **Default Template** | Page template for new pages  | (Optional)                  |

**To add a mapping:**

1. Click **+ Add Mapping**
2. Enter the Site Path
3. Enter the corresponding DAM Path
4. Optionally select a default template
5. Click Save

***

## Permissions

The Permissions tab allows you to verify your AEM user has the necessary access rights.

### Permission Testing

Select and run specific permission tests to verify your AEM user has the necessary access. Tests will create temporary artifacts and clean them up automatically.

**Available Tests:**

| Test                       | Verifies                                        |
| :------------------------- | :---------------------------------------------- |
| **Launch Permission**      | Ability to create and manage AEM Launches       |
| **Create Page Permission** | Ability to create new pages in configured paths |
| **Asset Permission**       | Ability to upload and manage DAM assets         |

**Running Tests:**

1. Check the boxes for tests you want to run
2. Click **Run Selected Tests** or **Test All Permissions**
3. Review results for any permission issues

**Troubleshooting Failed Tests:**

* Verify the AEM user credentials are correct
* Check that the user has the required group memberships in AEM
* Review AEM ACL configurations for the configured paths

***

## Domains

The Domains tab configures URL resolution from AEM paths to user-facing domains.

### Domain Mappings

Configure how AEM content paths map to live, user-facing URLs.

| Field             | Description              | Example                                      |
| :---------------- | :----------------------- | :------------------------------------------- |
| **AEM Path**      | The content path in AEM  | `/content`                                   |
| **Live Domain**   | The public-facing domain | `gradial.com`                                |
| **Regex Pattern** | Pattern for URL matching | `^(https?:\/\/)?(.*\.)?gradial\.com(\/.*)?$` |

**Adding a Domain Mapping:**

1. Click **+ Add Domain Mapping**
2. Enter the AEM Path (e.g., `/content/mysite`)
3. Enter the Live Domain (e.g., `www.mysite.com`)
4. Configure the regex pattern for URL matching
5. Click Save

**Use Cases:**

* Map AEM content paths to production URLs
* Support multiple domains for different content sections
* Enable URL validation in QA workflows

***

## Validation Rules Summary

### Template Paths

* **Must start with:** `/conf/`
* **Valid:** `/conf/wknd/settings/wcm/templates/xf-web-variation`
* **Invalid:** `/apps/templates/xf`

### Experience Fragment Paths

* **Must start with:** `/content/experience-fragments/`
* **Valid:** `/content/experience-fragments/wknd/heroes`
* **Invalid:** `/content/wknd/xf`

### Site Paths

* **Must start with:** `/content/`
* Exclude `/content/dam/` (use DAM Path field instead)

***

## Related Documentation

* [Navigating Workspaces and Settings in Gradial](https://app.gradial.com/)
* [Configuring Experience Fragment Defaults](https://www.notion.so/Configuring-Experience-Fragment-Defaults-2e37521d682e813ba989c83c16cd4303)
* AEM Multi Site Manager (MSM) Overview
* AEM Launches Documentation