> ## 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 Guides

> Set up Adobe Experience Manager Guides with Native PDF Publishing on AEM as a Cloud Service.

## Overview

[AEM Guides](https://experienceleague.adobe.com/en/docs/experience-manager-guides) is Adobe's enterprise-grade component content management system (CCMS) built on AEM. It enables structured authoring using the DITA standard, supports multi-channel publishing, and provides robust version control and translation workflows for technical documentation teams.

Gradial's AI agents integrate with AEM Guides to automate content creation, updates, translation tasks, and quality assurance across your DITA-based content libraries.

<Note>
  AEM Guides authoring operations are available only when the AEM Guides feature is enabled for your organization. Contact Gradial Support to request access.
</Note>

This page covers the full end-to-end setup for **Native PDF Publishing** on AEM as a Cloud Service (AEMaaCS), including the credential and OSGi configuration required to connect AEM author to Adobe's publishing microservice.

***

## What Native PDF Publishing Actually Requires

Three independent things must all be true:

1. **AEM Guides authoring entitlement** on the program — gives you the Web Editor, output presets UI, templates UI, and fmdita JCR setup. This is a paid Adobe add-on sold separately from base AEMaaCS Sites/Assets.
2. **AEM Guides publishing tenant provisioned by Adobe** — the customer-specific Adobe I/O Runtime tenant that renders PDFs. This is a separate Adobe-side provisioning step from #1. Contact your Adobe Customer Success representative to confirm this is in place.
3. **A correctly-scoped IMS service account** in your AEMaaCS environment — the OAuth Server-to-Server credential that AEM author uses to authenticate calls to the publishing tenant. This is the step most often misconfigured.

<Warning>
  If any of the three above is missing, PDF generation will silently fail. See [Troubleshooting](#troubleshooting) for the specific symptoms and fixes for each failure mode.
</Warning>

***

## Prerequisites

* An AEMaaCS program with AEM Guides provisioned by Adobe Customer Success
* Admin access to **Adobe Cloud Manager** (`experience.adobe.com`)
* Admin access to **Adobe Developer Console** (`developer.adobe.com/console`)
* Admin access to **Adobe Admin Console** (`adminconsole.adobe.com`)
* Ability to push to the implementation repository's `main` branch and trigger Cloud Manager pipelines
* AEM 6.5 or AEM as a Cloud Service with the AEM Guides add-on installed and licensed

***

## Authentication

AEM Guides runs on top of AEM, so authentication follows the same model as your underlying AEM environment:

* **AEM 6.5 with AEM Guides**: Use OAuth 2.0 authentication — refer to the [AEM 6.5 setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-on-prem).
* **AEM Cloud with AEM Guides**: Use Adobe IMS authentication — refer to the [AEM Cloud setup guide](/docs/integrations-administration-and-setup/integrations/aem/aem-cloud).

***

## Authoring capabilities

With AEM Guides enabled, Gradial can work directly with your DITA topics, maps, and configured publishing profiles.

| Workflow                             | What Gradial can do                                                                                                                                                                           |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Locate and copy a package**        | Find a ditamap under an approved DAM path, then copy the map and its referenced assets to a destination folder. Literal filename and content replacements can be applied as part of the copy. |
| **Create and manage assets**         | List compatible folder-profile templates, create DITA topics or maps, duplicate assets, rename them, or delete them after AEM Guides validates the change.                                    |
| **Edit topics and maps**             | Read and update DITA or DITAMAP XML, apply targeted text replacements, and add or remove map topic references.                                                                                |
| **Coordinate editing**               | Check an asset's lock state, then lock or unlock it before making a change.                                                                                                                   |
| **Replace topic images**             | Upload a replacement image into the topic folder and update the corresponding DITA image reference.                                                                                           |
| **Configure and publish PDF output** | List available presets and templates, create or update Native PDF or DITA-OT PDF presets, and run the selected output preset.                                                                 |

### Before you publish

* Grant Gradial read access to the Guides folders it needs to inspect and publish, plus create or edit access to every destination folder and asset it will modify.
* Review a copied package in AEM Guides before publishing: confirm the destination map, topics, referenced assets, and map references are the intended ones.
* Select a configured output preset by name. Native PDF is the default; DITA-OT publishing requires a folder profile that includes the required transformation.

***

## End-to-End Setup for Native PDF Publishing

### Phase 1 — Confirm AEM Guides is provisioned

1. In **Cloud Manager → Programs → your program → Solutions and Add-ons**, confirm "AEM Guides" appears.
2. If it doesn't appear, contact your Adobe Customer Success team — AEM Guides is a paid add-on with no self-serve provisioning path.
3. **Verify the publishing tenant exists.** When you fire a publish job, the output history entry's `cloudPublishJobId` field will be populated with a UUID (e.g., `bec82ef6-b151-44f2-9bcc-5db3b8b357d6`). If publishes get stuck in `outputStatus=Waiting` indefinitely, the tenant is not provisioned — open an Adobe Engineering ticket referencing your program ID.

***

### Phase 2 — Adobe Developer Console: OAuth credential

Adobe Developer Console is where you create the IMS service-account credential that AEM author uses to authenticate outbound calls to the publishing microservice.

**Use OAuth Server-to-Server, not JWT.** Adobe deprecated JWT credentials on June 30, 2025.

#### 2.1 Create or open the Developer Console project

1. Go to [https://developer.adobe.com/console](https://developer.adobe.com/console).
2. Confirm the org switcher (top-right) shows the same Adobe org that owns your AEMaaCS environment. If the org is wrong, every credential you create will fail with "different org" errors at runtime.
3. Open or create a project.

#### 2.2 Add APIs to the project

<Warning>
  This is the step that causes the most failures. The APIs you add determine which scopes the credential's access tokens carry.
</Warning>

Add these APIs (Add API → search):

| API                                 | Why it's needed                                                                                                                                                                                                                                                                         |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **I/O Management API**              | **Critical for Native PDF Publishing.** Grants `ent_adobeio_sdk` scope, which authorizes calls to `adobeioruntime.net`. Without it, publishing fails with `IMS credentials of different org are used` (Adobe's error message is misleading — the org is correct; the scope is missing). |
| **AEM Assets Author API**           | General AEM author API access                                                                                                                                                                                                                                                           |
| **AEM CS Sites Content Management** | AEM Sites API access                                                                                                                                                                                                                                                                    |

#### 2.3 Create the OAuth Server-to-Server credential

1. In the project, click **Add credential → OAuth Server-to-Server**.
2. Associate it with all the APIs added above.
3. Save. You'll receive `CLIENT_ID`, `CLIENT_SECRET`, `TECHNICAL_ACCOUNT_ID`, and scopes.

#### 2.4 Download the project JSON

1. Project overview → **Download** (top-right).
2. **Verify the scopes array contains `ent_adobeio_sdk`** before continuing. If it doesn't, the I/O Management API was not added correctly in step 2.2.

***

### Phase 3 — Cloud Manager: environment secret

1. Cloud Manager → Programs → your program → Environments → your env → **Configuration** tab.
2. Create environment variable **`SERVICE_ACCOUNT_DETAILS`** (type: Secret).
3. Value: paste the **complete contents** of the project JSON file from step 2.4 (the entire `{ "project": { ... } }` wrapper).
4. Save.

<Info>
  If migrating from a deprecated JWT setup, also delete the old `PRIVATE_KEY` variable if it exists.
</Info>

***

### Phase 4 — Code repository: OSGi configs

Three config files live in `ui.config/src/main/content/jcr_root/apps/<your-app>/osgiconfig/config.author.<env>/`. Create the same three files under each environment directory (`dev`, `stage`, `prod`).

**`com.adobe.aem.guides.eventing.ImsConfiguratorService.cfg.json`**

```json theme={null}
{
  "service.account.details": "$[secret:SERVICE_ACCOUNT_DETAILS]"
}
```

**`com.adobe.fmdita.publishworkflow.PublishWorkflowConfigurationService.cfg.json`**

```json theme={null}
{
  "dxml.publish.microservice.url": "https://adobeioruntime.net/api/v1/web/543112-guidespublisher/default/publishercaller.json",
  "dxml.use.publish.microservice": true,
  "dxml.use.publish.microservice.native.pdf": true
}
```

**`com.adobe.fmdita.config.ConfigManager.cfg.json`** *(optional)*

```json theme={null}
{
  "base.output.path": "/content/dam/fmdita-outputs",
  "ignored.post.processing.paths": [
    "/content/dam/projects/translation_output"
  ]
}
```

***

### Phase 5 — Deploy

Commit and push the OSGi config changes. Run a Cloud Manager pipeline to apply. If only the `SERVICE_ACCOUNT_DETAILS` secret was updated (no code changes), restart the AEM author tier via Cloud Manager → Environment → ⋮ → **Restart**.

***

### Phase 6 — AEM Author: templates and presets

#### Native PDF templates

The OOTB Native PDF templates ship with the AEM Guides module itself. Once Adobe enables AEM Guides on your program, three templates are already present in JCR at `/content/dam/dita-templates/pdf/`:

* `Basic`
* `Hi-Tech`
* `Prime`

If templates are missing, create a new one: AEM Author Web Editor → **Templates → Create new template → Native PDF**.

#### Output presets per ditamap

1. Open the ditamap in the Web Editor → **Map console → Output Presets**.
2. Click **+** to add a preset.
3. Configure: **Type: PDF**, **Target: Native PDF**, **Layout → Template**: pick your template.
4. Set the output path and PDF filename.
5. Click **Generate output** to test.

<Warning>
  Watch out for stale global presets stored at `/var/dxml/folderprofiles/global-profile/presets/<uuid>`. If a stale preset with an empty `templatePath` exists, every UI publish will silently use that stale config. Delete stale global presets via CRXDE Lite before relying on per-map presets.
</Warning>

***

## Verification

A successful Native PDF publish progresses through these states (poll `/var/dxml/metadata/outputHistory/<map-uuid>/<gen-id>.json`):

```
[0s]     outputStatus=Waiting,   cloudStatus=(none)
[5s]     outputStatus=Executing, cloudStatus=Started
[15s]    outputStatus=Executing, cloudStatus=Trigger-Successful   ← auth working
[5–20m]  outputStatus=Finished,  cloudStatus=Finished             ← rendering complete
```

**Reliable success signals:**

* `ditaotFaliure: false` (Adobe's typo) — this is the authoritative success flag
* `outputStatus: Finished` AND `cloudStatus: Finished`
* `outputPath` is populated

**Note:** `errorsExist: true` can appear even on a successful run (soft warnings about unresolvable hrefs). Do not use it as a failure signal.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Generate output queues a workflow but it hangs at outputStatus=Waiting">
    The Granite workflow engine accepted the job but the publish step is wedged. Most likely cause: the publishing tenant is not provisioned.

    **Fix:** Open an Adobe Engineering ticket referencing the program ID and workflow ID, and ask them to confirm the Guides publishing tenant is registered.
  </Accordion>

  <Accordion title="Workflow fails immediately with 'IMS credentials of different org are used'">
    Output shows `outputStatus=Finished, cloudStatus=Failed, ditaotFaliure=true`. Despite the error message, the org is almost certainly correct — the actual cause is the credential's access token is missing the `ent_adobeio_sdk` scope because the I/O Management API was not added to the Developer Console project.

    **Fix:** Adobe Developer Console → project → **Add API → I/O Management API** → associate with the existing OAuth S2S credential → download the project JSON → paste into Cloud Manager `SERVICE_ACCOUNT_DETAILS` → run a pipeline or restart the author pod.
  </Accordion>

  <Accordion title="outputStatus=Executing, cloudStatus=Trigger-Successful for 10+ minutes">
    This is **normal** for Native PDF rendering on a large map. Adobe I/O Runtime has accepted the job and is rendering. For a map with 50+ topics and many images, 10–20 minutes is typical. If it goes beyond 30 minutes, contact Adobe.
  </Accordion>

  <Accordion title="Templates → Layout dropdown shows only '(Default)'">
    The selected output preset has an empty `templatePath`. Usually caused by a stale global preset that referenced a deleted demo ditamap.

    **Fix:** Delete the stale global preset at `/var/dxml/folderprofiles/global-profile/presets/<uuid>` via CRXDE Lite. Create a fresh per-map preset and explicitly select a template.
  </Accordion>
</AccordionGroup>

***

## Support

Contact your Gradial onboarding lead or email [support@gradial.com](mailto:support@gradial.com) for help with setup.