### Install AEM Guides Extension Package via CLI

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/getting-started/integrating-customisations

This command initiates the installation of the AEM Guides extension framework using npx. Ensure you have Node.js and npm installed.

```bash
npx @adobe/create-guides-extension

```

--------------------------------

### Download Default DITA-OT from AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/dita-ot/setup-a-custom-dita-ot

This snippet shows the file path to download the out-of-the-box DITA-OT from AEM Guides. This is the starting point for creating a custom DITA-OT setup.

```text
/etc/fmdita/dita_resources/DITA-OT.zip
```

--------------------------------

### Installing AEM Guides API JARs Locally

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

Instructions on how to install the AEM Guides API JAR files into your local Apache Maven repository.

```APIDOC
## Installing the JARs on your local Apache Maven repository

To be able to use the JAR files exposed by AEM Guides, you need to install them on your local Apache Maven repository. Perform the following steps to install the JARs on your location Maven repository:

1. Extract the contents of the AEM Guides package (.zip) file on your local system.
2. In the command prompt, navigate to the following folder in the extracted content path:
```
\jcr_root\libs\fmdita\osgi-bundles\install
```

3. Run the following command to install the API bundle to your local Maven repository:
```
mvn install:install-file -Dfile=api-X.x.jar -DgroupId=com.adobe.fmdita -DartifactId=api -Dversion=X.x -Dpackaging=jar
```

**NOTE:** In the above command, X.x should be replaced with the actual version number in the Dfile and Dversion parameters.

4. (_Optional_) Install dependency in your local Maven project’s repository. You can achieve this by creating a folder in your Maven project and then running the `mvn install` command given in the previous step with the following additional parameter:
```
-DlocalRepositoryPath=<path_to_project_repository>
```

Next, to expose the project’s local repository folder to the Maven build process, add a `repository` element in the parent pom.xml file as shown below:
```xml
<repositories>
   <repository>
      <id>project-repository</id>
      <url>file://${project.basedir}/repository</url>
   </repository>
</repositories>
```
```

--------------------------------

### Install AEM Guides API JAR to Maven Repository

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

Installs the AEM Guides API JAR file into your local Apache Maven repository. This command requires replacing 'X.x' with the actual version number of the API.

```bash
mvn install:install-file -Dfile=api-X.x.jar -DgroupId=com.adobe.fmdita -DartifactId=api -Dversion=X.x -Dpackaging=jar
```

--------------------------------

### Verify Installation Completion with Log Messages

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

This section provides expected log messages that confirm the successful completion of the Experience Manager Guides 4.2 installation and post-deployment setup.

```log
Completed the post deployment setup script
```

--------------------------------

### Resolving Incorrect Setup of AEM Guides Components

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/-learn/videos/output-generation/troubleshooting-publishing-errors

This snippet addresses errors arising from the incorrect setup of components used by AEM Guides. Administrators are responsible for resolving these issues by updating system installations, components, or permissions.

```text
Administrators can update the installation of the system, its components, or permissions.
```

--------------------------------

### Configure Child Module pom.xml for AEM Guides API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

Configures a child module's pom.xml file to use the maven-install-plugin to install the AEM Guides API JAR. This example uses version 3.6.

```xml
<plugin>
   <groupId>org.apache.maven.plugins</groupId>

   <artifactId>maven-install-plugin</artifactId>

   <configuration>

      <groupId>com.adobe.fmdita</groupId>

      <artifactId>api</artifactId>

      <version>3.6</version>

      <file>${basedir}/../dependencies/fmdita/api-3.6.jar</file>

      <packaging>jar</packaging>

      <generatePom>true</generatePom>

   </configuration>

   <executions>

      <execution>

         <id>inst_fmdita</id>

         <goals>

            <goal>install-file</goal>

         </goals>

         <phase>clean</phase>

      </execution>

   </executions>

</plugin>
```

--------------------------------

### Maven Project Structure for AEM Guides Components

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/aem-site-templates/download-install-aem-sites-templates-cs-kb

This describes the required directory structure within a Maven project to properly include AEM Guides components. The zip file is placed in the 'install' folder.

```text
/jcr_root/apps/fmdita/install
```

--------------------------------

### Sample JSON for AEM Guides Topic to Content Fragment Mapping

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/cs-ig/output-gen-config-cs/conf-content-fragment-mapping-cs

Provides a practical example of a JSON file used for mapping content from AEM Guides topics to content fragment models. It demonstrates two mapping configurations: 'Full Topic' for publishing all content and 'Sample Example with XPath' for specific element mapping.

```json
[
  {
    "mapping": [
      {
        "modelField": "title",
        "xpath": "/topic[1]/title[1]",
        "outputType": "textContent"
      },
      {
        "modelField": "shortdesc",
        "xpath": "/topic[1]/shortdesc[1]",
        "outputType": "textContent"
      },
      {
        "modelField": "topicData",
        "xpath": "/topic[1]/body[1]",
        "outputType": "outerHTML"
      }
    ],
    "name": "Full Topic"
  },
  {
    "mapping": [
      {
        "modelField": "title",
        "xpath": "/topic[1]/title[1]",
        "outputType": "textContent"
      },
      {
        "modelField": "shortdesc",
        "xpath": "/topic[1]/shortdesc[1]",
        "outputType": "textContent"
      },
      {
        "modelField": "heroImage",
        "xpath": "/topic[1]/body[1]/p[1]/image[1]",
        "outputType": "outerHTML"
      },
      {
        "modelField": "dataTable",
        "xpath": "/topic[1]/body[1]/table[1]",
        "outputType": "outerHTML"
      }
    ],
    "name": "Sample Example with XPath"
  }
]
```

--------------------------------

### Overlay and Clientlib Validation Example

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

This section provides examples of customizations that need validation after an upgrade, including overlayed components from /libs/fmdita, clientlib categories, and overridden configurations like elementmapping.xml and ui_config.json.

```text
* Any components overlayed from/libs/fmditaor/libsshould be compared with the new product code and updates should be done in overlayed files under/apps.
* Any clientlib categories used from product, should be reviewed for changes. Any overridden configurations (examples below) should be compared with the latest ones so as to get the latest features:
* elementmapping.xml
* ui_config.json(may have been set in folder profiles)
* amended `com.adobe.fmdita.config.ConfigManager`
```

--------------------------------

### Identify Installation Errors

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

This lists common error prefixes that may appear during the Experience Manager Guides 4.2 installation. Encountering these errors requires reporting them to the customer success team for resolution.

```log
Error in post deployment setup script
```

```log
Exception while porting the translation MAP
```

```log
Unable to port translation map from v1 to v2 for property
```

--------------------------------

### Example JSON Structure for UI Configuration

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/-learn/videos/advanced-user-guide/conver-ui-config_lang=en

Illustrates the general JSON structure used for customizing AEM Guides UI components. It shows how to specify the target widget (`id`), conditional display (`targetEditor`), and placement (`target`). This example demonstrates prepending an item to the 'editor_toolbar' when in 'preview' mode and the 'xml' editor.

```json
{
  "id" : "editor_toolbar",
  "view": {
    "items": [
      {
        "...": "...",
        "targetEditor": {
          "mode": [
            "preview"
          ],
          "editor": [
            "xml"
          ]
        },
        "target": {
          "key": "label",
          "value": "Table",
          "viewState": "prepend"
        },
        "...": "..."
      },
    ]
  }
}
```

--------------------------------

### Build Customized AEM Guides Extension Code

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/getting-started/integrating-customisations

This command builds the customized extension code. It generates CSS and JavaScript files in the 'dist/' directory.

```bash
npm run build

```

--------------------------------

### Configure Parent pom.xml for AEM Guides API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

Configures the parent project's pom.xml file to use the maven-install-plugin to install the AEM Guides API JAR. Replace 'X.x' with the actual version number.

```xml
<plugin>

    <groupId>org.apache.maven.plugins</groupId>

   <artifactId>maven-install-plugin</artifactId>

    <version>2.5.2</version>

    <configuration>

            <groupId>com.adobe.fmdita</groupId>

            <artifactId>api</artifactId>

            <version>X.x</version>

            <file>${basedir}/dependencies/fmdita/api-X.x.jar</file>

            <packaging>jar</packaging>

            <generatePom>true</generatePom>

    </configuration>

    <executions>

        <execution>

            <id>inst_fmdita</id>

                <goals>

                    <goal>install-file</goal>

                </goals>

                <phase>clean</phase>

        </execution>

    </executions>
</plugin>
```

--------------------------------

### Filter AEM Guides Bundles

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/download-install-verify-aemg-installation

This snippet demonstrates how to filter the list of bundles in the AEM Web Console to find those installed by AEM Guides. The filtering is done by entering 'fmdita' into a text box.

```text
fmdita
```

--------------------------------

### Index Content for Find and Replace (API)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2504-release/upgrade-instructions-2025-04-0

Starts an indexing process for content in Experience Manager Guides to enable new find and replace features. Supports indexing specific map paths or content within a root folder. Returns a jobId for status tracking via GET requests.

```bash
POST http://<server:port>/bin/guides/map-find/indexing?paths=<path of the MAP in repository>
POST http://<server:port>/bin/guides/map-find/indexing?root=/content/dam/test
GET http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}
```

--------------------------------

### Access AEM CRX Package Manager URL

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/download-install-aemg-first-time

This snippet shows the default URL to access the Package Manager in an AEM instance, which is used for installing AEM Guides.

```text
/crx/packmgr/
```

--------------------------------

### Embed Azure DevOps Connector Dependency

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/cs-ig/web-editor-configs-cs/conf-data-source-connector-tools

This snippet demonstrates how to embed the previously added Maven dependency into the Adobe Experience Manager Guides Cloud Service environment. The `target` path specifies where the connector will be installed.

```xml
<embedded>
     <groupId>com.adobe.aem.addon.guides</groupId>
     <artifactId>konnect-azure-devops</artifactId>
     <type>jar</type>
     <target>/apps/aemdoxonaemcsstageprogram-vendor-packages/content/install</target>
 </embedded>
```

--------------------------------

### Customize Context Menu Options in AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/customisations/examples

This example demonstrates how to customize the 'file_options' context menu in AEM Guides. It shows how to remove specific options like 'Delete' and 'Edit', and replace 'Duplicate' with a 'Download' option.

```javascript
guides_extension/src
```

--------------------------------

### Using the AEM Guides Service API JAR in a Maven Project

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

Steps to configure your Maven project to use the installed AEM Guides API JARs.

```APIDOC
## Using the service API JAR in a Maven project

After installing the API JARs in your local Maven repository, perform the following steps to use the JAR in your projects:

1. Add the JAR to your code base and commit it to the code base repository under a folder, such as “dependencies”. Note that the folder name depends on your code base hierarchy.
2. Configure the project pom.xml files as follows:

**Parent project’s pom.xml file:**

**IMPORTANT:** In the following code snippet, X.x should be replaced with the actual version number and the API JAR’s file name. This information will be same as given in the Step 3 of the installation process.

```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-install-plugin</artifactId>
    <version>2.5.2</version>
    <configuration>
            <groupId>com.adobe.fmdita</groupId>
            <artifactId>api</artifactId>
            <version>X.x</version>
            <file>${basedir}/dependencies/fmdita/api-X.x.jar</file>
            <packaging>jar</packaging>
            <generatePom>true</generatePom>
    </configuration>
    <executions>
        <execution>
            <id>inst_fmdita</id>
                <goals>
                    <goal>install-file</goal>
                </goals>
                <phase>clean</phase>
        </execution>
    </executions>
</plugin>
```

**Child module’s pom.xml file:**

```xml
<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-install-plugin</artifactId>
   <configuration>
      <groupId>com.adobe.fmdita</groupId>
      <artifactId>api</artifactId>
      <version>3.6</version>
      <file>${basedir}/../dependencies/fmdita/api-3.6.jar</file>
      <packaging>jar</packaging>
      <generatePom>true</generatePom>
   </configuration>
   <executions>
      <execution>
         <id>inst_fmdita</id>
         <goals>
            <goal>install-file</goal>
         </goals>
         <phase>clean</phase>
      </execution>
   </executions>
</plugin>
```
```

--------------------------------

### Update Dialog to Add Publish Button in AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/customisations/examples

This example shows how to update an existing dialog in AEM Guides to include a 'publish' button. It allows for modification of the dialog's content, with the JSON configuration available at 'save_revision'.

```javascript
save_revision
```

--------------------------------

### Start B-Tree Migration Job

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2504-release/upgrade-instructions-2025-04-0

Initiates the B-Tree migration job for content fragments. This is useful when references are not displayed correctly.

```APIDOC
## POST /bin/guides/script/start

### Description
Triggers the B-Tree migration script for content fragments to resolve reference display issues.

### Method
POST

### Endpoint
`http://localhost:4503/bin/guides/script/start`

### Query Parameters
- **jobType** (string) - Required - Specifies the type of job to start, e.g., `cf-reference-store-btree-migration`.

### Request Example
```json
{
  "message": "Initiating CF reference store B-Tree migration job."
}
```

### Response
#### Success Response (200)
- **msg** (string) - Confirmation message indicating the job submission.
- **lockNodePath** (string) - The repository path to the lock node created for the job.
- **status** (string) - The initial status of the submitted job (e.g., `SCHEDULED`).

#### Response Example
```json
{
  "msg": "Job is successfully submitted and lock node is created for future reference",
  "lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
  "status": "SCHEDULED"
}
```
```

--------------------------------

### Index Existing Content via API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2303-release/release-notes-2023-3-0

This shows how to initiate and check the status of content indexing using a POST and GET request to the AEM Guides server. It supports indexing all maps or specific paths.

```bash
http://<server:port>/bin/guides/map-find/indexing
http://<server:port>/bin/guides/map-find/indexing?paths=<map_path_in_repository>
http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}
```

--------------------------------

### Trigger Content Fragment B-Tree Migration (Experience Manager Guides)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2024-releases/2412-release/upgrade-instructions-2024-12-0

Starts a B-Tree migration job for Content Fragments in Experience Manager Guides to resolve reference display issues. Submits a POST request and provides a lock node path in the response for job status monitoring.

```HTTP
POST http://localhost:4503/bin/guides/script/start?jobType=cf-reference-store-btree-migration
```

```JSON
{
"msg": "Job is successfully submitted and lock node is created for future reference",
"lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
"status": "SCHEDULED"
}
```

```HTTP
GET http://<aem_domain>/var/dxml/executor-locks/cf-reference-store-btree-migration/{lockNodePath}.json
```

--------------------------------

### Index Existing Content with AEM Guides API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2310-release/release-notes-2023-10-0

This snippet demonstrates how to index existing content in AEM Guides using a POST request to the server. It includes optional parameters for specifying paths or a root folder for indexing. The process returns a jobId to track the indexing status via a GET request.

```HTTP
POST http://<server:port>/bin/guides/map-find/indexing

GET http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}

GET http://<server:port>/bin/guides/map-find/indexing?paths=<map_path_in_repository>

GET http://<server:port>/bin/guides/map-find/indexing?root=/content/dam/test
```

--------------------------------

### Example DITA Element Usage in AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/user-guide/author-content/create-preview-topics/author-content-aem-guides/work-with-web-editor/web-editor-other-features

Illustrates the use of common DITA elements like 'p', 'note', 'pre', and 'codeblock' within the AEM Guides editor, highlighting how these elements handle content structure and formatting, including white space and line breaks.

```xml
<note>
  <p>This is a note.</p>
</note>
<p>This is a paragraph.</p>
<pre>
  This is preformatted text.
  With line breaks.
</pre>
<codeblock>
  This is a code block.
  Indentation is preserved.
</codeblock>
```

--------------------------------

### Install Content Transfer Tool Package

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/cs-ig/migrate-con-cs/migrate-on-premise-content-cloud

This snippet shows the command to install the Content Transfer Tool package in the Package Manager of your on-premise AEM instance. Ensure you are using the latest version.

```bash
Upload and install the package `content-transfer.all-3.0.10.zip` in the **Package Manager** of your On-premise instance.
```

--------------------------------

### Index Existing Content with AEM Guides API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2302-release/release-notes-2023-2-0

API endpoints for indexing existing content in AEM Guides. It includes a POST request to initiate indexing and a GET request to check the job status using a provided job ID. Optional paths can be specified for targeted indexing.

```http
POST http://<server:port>/bin/guides/map-find/indexing

```

```http
GET http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}

```

```http
GET http://<_localhost:8080_ >/bin/guides/map-find/indexing?jobId=2022/9/15/7/27/7dfa1271-981e-4617-b5a4-c18379f11c42_678

```

```http
GET https://<Server:port>/bin/guides/map-find/indexing?paths=<map_path_in_repository>

```

--------------------------------

### Project Directory Structure

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/getting-started/extension-repo-intro

This snippet shows the overall file and folder structure for the AEM Guides extension project. It includes source files, build outputs, dependencies, configuration files, and JSON assets.

```tree
├── src
│   ├── **/*{js,ts}
│   ├── index.ts
├── dist
│   ├── guides-extension.js
│   ├── guides-extension.umd.cjs
│   ├── build.css
├── node_modules
├── package.json
├── package-lock.json
└── .gitignore
└── buildCSS.mjs // for creating tailwind classes
└── vite.config.js // config for specifying TS and javascript build options
└── taliwind.config.js // config for tailwind we can add custom config for a design system here
├── jsons // jsons for the aem app
│   ├── context_menus // jsons for the context menus
│   ├── review_app // jsons for the review app
│   ├── xmleditor // jsons for xmleditor

```

--------------------------------

### Configure AEM Site Preset Options

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/aem-site-templates/download-install-aem-sites-templates-prem-kb

Demonstrates two methods for configuring an AEM Site preset. Option 1 uses a dropdown selection for the site, while Option 2 allows manual setting of the site path.

```json
Option 1: Use the Site Dropdown
Select Site as AEMG Docs.
Verify that the Publish path and Topic page template are automatically set to:
Publish path: aemg-docs/en/docs/product1
Topic page template: Topic Page.

Option 2: Use the Site Path
Set the Site path manually as /content/aemg-docs/en/docs/product1.
Verify that the Topic page template is automatically set to Topic Page.
```

--------------------------------

### Index Existing Content via API (POST)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2304-release/release-notes-2023-4-0

This code snippet demonstrates how to initiate the indexing of existing content using a POST request to the AEM Guides server. It includes the endpoint and optional parameters for specifying content paths.

```http
POST http://<server:port>/bin/guides/map-find/indexing
(Optional: ?paths=<map_path_in_repository>)
```

--------------------------------

### POST /bin/guides/script/start

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2506-release/upgrade-instructions-2025-06-0

Triggers the B-Tree migration job for Content Fragments if references are not displayed.

```APIDOC
## POST /bin/guides/script/start

### Description
Initiates the B-Tree migration job for Content Fragments. This is typically used when references are not displayed correctly.

### Method
POST

### Endpoint
http://localhost:4503/bin/guides/script/start

### Query Parameters
- **jobType** (string) - Required - Specifies the type of job to start, e.g., `cf-reference-store-btree-migration`.

### Request Example
```json
{
  "message": "Triggering B-Tree migration job for Content Fragments"
}
```

### Response
#### Success Response (200)
- **msg** (string) - Confirmation message that the job has been submitted.
- **lockNodePath** (string) - The path to the lock node created in the repository for monitoring the job.
- **status** (string) - The initial status of the job (e.g., `SCHEDULED`).

#### Response Example
```json
{
  "msg": "Job is successfully submitted and lock node is created for future reference",
  "lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
  "status": "SCHEDULED"
}
```
```

--------------------------------

### POST /bin/guides/script/start

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2506-release/upgrade-instructions-2025-06-0

This endpoint is used to trigger a script for the translation map upgrade job. It is relevant for users on releases prior to the June 2023 release of Experience Manager Guides as a Cloud Service.

```APIDOC
## POST /bin/guides/script/start

### Description
Triggers a script for the translation map upgrade job.

### Method
POST

### Endpoint
`http://localhost:4503/bin/guides/script/start`

### Query Parameters
- **jobType** (string) - Required - Specifies the type of job to start, e.g., `translation-map-upgrade`.

### Request Example
```json
{
  "message": "Job submitted"
}
```

### Response
#### Success Response (200)
- **msg** (string) - Confirmation message that the job is submitted.
- **lockNodePath** (string) - Path to the lock node created in the repository for the job.
- **status** (string) - The status of the submitted job (e.g., "SCHEDULED").

#### Response Example
```json
{
  "msg": "Job is successfully submitted and lock node is created for future reference",
  "lockNodePath": "/var/dxml/executor-locks/translation-map-upgrade/1683190032886",
  "status": "SCHEDULED"
}
```
```

--------------------------------

### Handling Duplicate GUIDs During Template Installation

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2024-releases/2406-release/fixed-issues-2024-06-0

Addresses content deletion issues caused by duplicate GUIDs when templates are installed via code and remain unprocessed. This ensures data integrity by correctly managing unique identifiers.

```java
import java.util.HashSet;
import java.util.Set;

// ... inside a method processing templates ...
Set<String> guids = new HashSet<>();
for (Template template : templates) {
    if (!guids.add(template.getGuid())) {
        // Handle duplicate GUID: log warning, skip, or report error
        System.err.println("Duplicate GUID found: " + template.getGuid() + " for template: " + template.getName());
    } else {
        // Process the template with a unique GUID
        processTemplate(template);
    }
}
```

--------------------------------

### Configure environment for the first time with OAuth JSON

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/configure-microservices-imt-config

This snippet outlines the process of configuring an Experience Manager Guide environment for the first time using OAuth authentication. It involves creating a new configuration named SERVICE_ACCOUNT_DETAILS and populating it with the content of the OAuth JSON file downloaded from the Adobe Developer Console.

```json
{
  "SERVICE_ACCOUNT_DETAILS": "<content_of_oauth_json_file>"
}
```

--------------------------------

### Example Variables for PDF Output - AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/output-gen-config/config-native-pdf-publish/native-pdf-variables

Demonstrates the creation of variables with example values for use in PDF output generation within Adobe Experience Manager Guides. Variables allow for reusable and easily updatable pieces of information.

```text
ProductName: Experience Manager Guides
VersionNumber: 2300
ReleaseDate: 01/01/2023
```

--------------------------------

### Sample Event Listener Implementation

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/bulk-activation-complete-event

A Java code example demonstrating how to implement an event listener for the bulk activation complete event.

```APIDOC
## Sample Event Listener

### Description
This Java code snippet shows how to create an AEM event handler to listen for the `com/adobe/fmdita/replication/complete` event and process its properties.

### Method
Java (OSGi Component)

### Endpoint
N/A (Listens to an event topic)

### Parameters
(Event properties are accessed via the `Event` object)

### Request Example
(N/A)

### Response
#### Success Response (200)
(Listener processes events, no specific response for the listener itself)

#### Response Example
```java
@Component(service = EventHandler.class,
        immediate = true,
        property = {
                EventConstants.EVENT_TOPIC + "=" + "com/adobe/fmdita/replication/complete",
        })

public class SampleEventHandler implements EventHandler {

    protected final Logger log = LoggerFactory.getLogger(this.getClass());

    @Override
    public void handleEvent(final Event event) {
        Map<String, String> properties = new HashMap<>();
        properties.put("paths", (String) event.getProperty("paths"));
        properties.put("messageType", (String) event.getProperty("messageType"));
        properties.put("action", (String) event.getProperty("action"));
        properties.put("result", (String) event.getProperty("result"));
        properties.put("user", (String) event.getProperty("user"));
        properties.put("agentId", (String) event.getProperty("agentId"));
        properties.put("importMode", (String) event.getProperty("importMode"));

        String eventTopic = event.getTopic();
        log.debug("eventTopic {}", eventTopic);
        for(Map.Entry entry:properties.entrySet()) {
            log.debug(entry.getKey() + " : " + entry.getValue());
        }

    }
}
```
```

--------------------------------

### Check AEM Guides Broken Link Report Job Status (GET)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2309-release/release-notes-2023-9-0

This snippet shows how to check the status of a broken link report job in AEM Guides. After initiating the process with a POST request, a GET request including the jobId is used to monitor the job's completion.

```HTTP
GET http://<server:port>/bin/guides/reports/upgrade?jobId= {jobId}
```

--------------------------------

### Check AEM Guides Translation Job Status via Servlet (GET)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2309-release/release-notes-2023-9-0

This snippet demonstrates how to check the status of a translation job initiated via a servlet in AEM Guides. It uses a GET request with the lock node path obtained from the initial POST request to query the job's progress.

```HTTP
GET http://<aem_domain>/var/dxml/executor-locks/translation-map-upgrade/1683190032886.json
```

--------------------------------

### AEM Guides Publishing Benchmarks - Execution Environment

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/publishing-benchmarks-on-cloud

Details the specific AEM release, Guide Add-On release, AEM Site Template, DITA-OT version, Publish Workflow Type, and output formats supported by the microservice for benchmarking.

```text
AEM Release: 2023.5.11983.20230511T173830Z
Guide Add On Release: 2023.6.0
AEM Site Template: AEM Guides OOTB template
DITA-OT version: 3.5.4
Publish Workflow Type: Split Publish Workflow
Output supported by microservice: Native PDF, PDF (Dita-OT)
```

--------------------------------

### Calculate and Assign Unique Comment IDs in AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/customisations/examples

This example covers the logic for calculating and assigning unique comment IDs within the Inline Review Panel of AEM Guides. It details methods for setting comment IDs based on count, setting user information, and event handling for new comments.

```javascript
setCommentId: Sets the unique comment ID.
setUserInfo: Sets user information (full name, title).
onNewCommentEvent: Ensures setUserInfo is called for new comments/replies.
updatedProcessComments: Ensures setCommentId is called for new comment events.
```

--------------------------------

### Run Broken Link Report Upgrade API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

These API calls are used to initiate and monitor a post-processing job for broken link reports. The POST request starts the process and returns a job ID, while the GET request tracks the job's status.

```bash
POST http://<server:port>/bin/guides/reports/upgrade
GET http://<server:port>/bin/guides/reports/upgrade?jobId=<jobId>
```

--------------------------------

### AEM Guides Logger Configuration

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/cs-ig/appendix

Instructions on configuring a specific logger for AEM Guides script execution to aid in debugging and troubleshooting.

```APIDOC
## Logger Configuration for AEM Guides Scripts

### Description
Configure a logger for the 'adobe.fmdita.common.BTreeReferenceValidator' class to DEBUG level for detailed script execution logs.

### Logger Class
`adobe.fmdita.common.BTreeReferenceValidator`

### Log Level
`DEBUG`

### Purpose
This logger captures detailed information related to script execution, which is useful for diagnosing issues, especially in scenarios where browser sessions might timeout during script triggering.
```

--------------------------------

### POST /bin/guides/script/start?jobType=cf-reference-store-btree-migration

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2024-releases/2412-release/upgrade-instructions-2024-12-0

Triggers a B-Tree migration job for Content Fragments to resolve issues with displaying references.

```APIDOC
## POST /bin/guides/script/start?jobType=cf-reference-store-btree-migration

### Description
Triggers a B-Tree migration job for Content Fragments. This is used to resolve issues where references are not displayed correctly.

### Method
POST

### Endpoint
`http://<server:port>/bin/guides/script/start?jobType=cf-reference-store-btree-migration`

### Parameters
#### Query Parameters
- **jobType** (string) - Required - Must be set to `cf-reference-store-btree-migration`.

### Request Example
`http://localhost:4503/bin/guides/script/start?jobType=cf-reference-store-btree-migration`

### Response
#### Success Response (200)
- **msg** (string) - Confirmation message indicating the job submission.
- **lockNodePath** (string) - The path to the lock node created in the repository for the job.
- **status** (string) - The initial status of the job (e.g., "SCHEDULED").

#### Response Example
```json
{
  "msg": "Job is successfully submitted and lock node is created for future reference",
  "lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
  "status": "SCHEDULED"
}
```
```

--------------------------------

### Verify Java installation with Node.js in AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/configuring-aem-environment-for-native-pdf-publishing

This demonstrates how to verify the Java installation within the AEM Guides environment by executing a Node.js script that requires the 'java' module. This checks if Java is accessible via the Node.js runtime.

```javascript
a = require(‘java’)
```

--------------------------------

### POST /bin/guides/script/start

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

Triggers a script execution, such as a translation map upgrade. It accepts a job type as a query parameter and returns a job status, including a lock node path for monitoring.

```APIDOC
## POST /bin/guides/script/start

### Description
This endpoint is used to trigger the execution of a specific script. It is particularly useful for background tasks like upgrading translation maps. A `jobType` query parameter specifies the script to run.

### Method
POST

### Endpoint
`/bin/guides/script/start`

### Parameters
#### Query Parameters
- **jobType** (string) - Required - Specifies the type of job to execute (e.g., `translation-map-upgrade`).

### Request Example
{
  "example": "http://localhost:4503/bin/guides/script/start?jobType=translation-map-upgrade"
}

### Response
#### Success Response (200)
- **msg** (string) - A message indicating the job submission status.
- **lockNodePath** (string) - The repository path to the lock node created for monitoring the job.
- **status** (string) - The current status of the job (e.g., `SCHEDULED`).

#### Response Example
{
  "example": "{\n  \"msg\": \"Job is successfully submitted and lock node is created for future reference\",\n  \"lockNodePath\": \"/var/dxml/executor-locks/translation-map-upgrade/1683190032886\",\n  \"status\": \"SCHEDULED\"\n}"
}
```

--------------------------------

### Check Indexing Job Status via API (GET)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2023-releases/2304-release/release-notes-2023-4-0

This code snippet shows how to check the status of an indexing job using a GET request to the AEM Guides server. It requires the jobId returned from the initial POST request.

```http
GET http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}
```

--------------------------------

### Index Existing Content using API

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

Provides instructions on how to index existing content in Experience Manager Guides using API calls. It includes the endpoint for initiating the indexing job and checking its status.

```bash
POST http://<server:port>/bin/guides/map-find/indexing
GET http://<server:port>/bin/guides/map-find/indexing?jobId=<jobId>
```

--------------------------------

### Upgrade Path for AEM Guides to 4.3.1

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/on-prem-release-notes/43-release/43-release-notes/release-notes-4-3-1

This snippet outlines the direct and indirect upgrade paths for various versions of Adobe Experience Manager Guides to version 4.3.1. It emphasizes the need to install AEM service packs before upgrading Experience Manager Guides.

```text
If you are using version 4.3.0, 4.2, or 4.2.1, then you can directly upgrade to version 4.3.1.
If you are using version 4.1 or 4.1.x then you need to upgrade to version 4.3.0, 4.2 or 4.2.x before upgrading to version 4.3.1.
If you are using version 4.0 you need to upgrade to version 4.2 before upgrading to version 4.3.1.
If you are using version 3.8.5, you need to upgrade to version 4.0 before upgrading to version 4.2.
You must install AEM service pack before upgrading Experience Manager Guides version.
```

--------------------------------

### Example XML Configuration for Word to DITA Conversion (w2d_io.xml)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/cs-ig/migrate-con-cs/migrate-content-non-dita

This snippet shows an example of the `w2d_io.xml` configuration file used by AEM Guides for converting Word documents to DITA. It includes parameters for input and output directories, version creation, style-to-tag mapping, and properties to propagate.

```xml
<config>
  <inputDir>/content/dam/projects/wordtodita/</inputDir>
  <outputDir>/content/dam/projects/dita_output/</outputDir>
  <createRev>true</createRev>
  <s2tMap>/libs/fmdita/word2dita/word-builtin-styles-style2tagmap.xml</s2tMap>
  <props2Propagate>
    <prop>dc:title</prop>
    <prop>dc:subject</prop>
    <prop>dam:keywords</prop>
    <prop>dam:category</prop>
  </props2Propagate>
</config>
```

--------------------------------

### API Request for Content Indexing

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2508-release/upgrade-instructions-2025-08-0

This POST request triggers the indexing of existing content for Experience Manager Guides' find and replace and topic list features. It accepts optional `paths` or `root` parameters to specify content for indexing. The response provides a `jobId` for status tracking.

```http
POST http://<server:port>/bin/guides/map-find/indexing?paths=<path of the MAP in repository>
POST http://<server:port>/bin/guides/map-find/indexing?root=/content/dam/test

GET http://<server:port>/bin/guides/map-find/indexing?jobId={jobId}
```

--------------------------------

### POST /bin/guides/script/start?jobType=cf-reference-store-btree-migration - Start B-Tree Migration

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2024-releases/2410-0-release/upgrade-instructions-2024-10-0

Triggers the B-Tree migration job for Content Fragments to ensure references are displayed correctly.

```APIDOC
## POST /bin/guides/script/start?jobType=cf-reference-store-btree-migration

### Description
Starts a job to migrate Content Fragment references using the B-Tree structure. This is a necessary step if references are not being displayed correctly for Content Fragments.

### Method
POST

### Endpoint
`http://<aem_domain>/bin/guides/script/start`

### Query Parameters
- **jobType** (string) - Required - Specifies the type of job to start. Must be `cf-reference-store-btree-migration`.

### Request Example
```json
{
  "example": "POST http://localhost:4503/bin/guides/script/start?jobType=cf-reference-store-btree-migration"
}
```

### Response
#### Success Response (200)
- **msg** (string) - Confirmation message indicating the job submission.
- **lockNodePath** (string) - The path to the lock node created in the repository for tracking the job.
- **status** (string) - The initial status of the job, typically "SCHEDULED".

#### Response Example
```json
{
  "msg": "Job is successfully submitted and lock node is created for future reference",
  "lockNodePath": "/var/dxml/executor-locks/cf-reference-store-btree-migration/1683190032886",
  "status": "SCHEDULED"
}
```
```

--------------------------------

### Create ECMA Workflow Process for AEM Guides

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/workflows/using-post-generation-workflow

This snippet demonstrates creating a workflow process using ECMA script for post-output generation in AEM Guides. It allows for custom operations on generated content, such as metadata manipulation. Refer to the 'Installation and configuration guide' for Java-based workflows.

```ecmascript
/*
  Sample ECMA script for AEM Guides post-generation workflow.
  This script can be customized to perform operations on the generated output.
  Example: Copying metadata from source to generated content or manipulating metadata.
*/

// Function to be called by the workflow engine
function process(currentNode, workflowSession, metaData) {
    // Get the output path from metadata or context
    var outputLocation = metaData.get('outputLocation');

    if (outputLocation) {
        // Perform custom operations on the output at outputLocation
        // For example, read/write files, manipulate XML/JSON, etc.
        log.info('Processing output at: ' + outputLocation);

        // Example: Manipulate metadata of the generated output
        // This would typically involve interacting with the JCR or specific output file formats

        // Example: Send an email notification
        // This would involve using AEM's email service

    } else {
        log.error('Output location not found in metadata.');
    }

    // Return success or failure status
    return true;
}
```

--------------------------------

### Add AEM Guides Service API JAR Dependency (Public Repository)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/introduction

This XML snippet demonstrates how to add the AEM Guides service API JAR as a project dependency in your Maven project's pom.xml. Ensure the version matches your installed AEM Guides package.

```xml
<dependency>
   <groupId>com.adobe.fmdita</groupId>
   <artifactId>api</artifactId>
   <version>4.0</version>
</dependency>
```

--------------------------------

### Build Output Directory Structure

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/extention-framework/getting-started/extension-repo-intro

Illustrates the contents of the 'dist' directory, which contains the compiled and optimized output files for the extension. This includes JavaScript bundles in both ES module and UMD formats, as well as the generated CSS file.

```tree
├── dist
│   ├── gudies-extension.js // you can either choose es module (this one) or .cjs(other one) file
│   ├── gudies-extension.umd.cjs
│   ├── build.css // this is your tailwind css output

```

--------------------------------

### Query DITA map export status (GET)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/api-reference/dita-map-management

Retrieves the current status of an ongoing or completed DITA map export job using its unique `jobId`. This API can be polled periodically to monitor progress. The response indicates the status (e.g., STARTED, SUCCEED, FAILED) and may include a `filePath` for successful exports.

```HTTP
GET http://<aem-guides-server>:<port-number>/bin/dxml/async-export?jobId=YOUR_JOB_ID
```

--------------------------------

### Configure DAM Update Asset Workflow Step

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/install-guide/on-prem-ig/download-install-upgrade-aemg/upgrade-xml-documentation

This snippet details the configuration of the 'DXML Post Process Initiator' component within the DAM Update Asset workflow. It specifies the Title, Description, Process, and Handler Advance settings required for Experience Manager Guides post-processing.

```text
**Title:** DXML Post Process Initiator
**Description** : DXML post process initiator step which will trigger a sling job for DXML post-processing of the modified/created asset
**Process tab**
     * Select **DXML Post Process Initiator** from the **Process** drop down
     * Select **Handler Advance**
     * Select **Done**
```

--------------------------------

### Configure Query Limits for Large Content Sets (Java)

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2025-releases/2502-release/upgrade-instructions-2025-02-0

Adjusts 'queryLimitReads' and 'queryLimitInMemory' for systems with over 100,000 DITA files. This requires creating a configuration file to override default service settings, enhancing performance for large content operations.

```properties
org.apache.jackrabbit.oak.query.QueryEngineSettingsService.config=
queryLimitReads=200000
queryLimitInMemory=200000
```

--------------------------------

### Execute npm install with specified node path on Mac

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/knowledge-base/kb-articles/publishing/configuring-aem-environment-for-native-pdf-publishing

These commands are executed from the AEM installation path to set file permissions and install npm packages using a specific Node.js executable. This is crucial for the AEM Guides' functionality.

```shell
find . -type d -exec chmod 0755 {} ;
```

```shell
find . -type f -exec chmod 0755 {} ;
```

```shell
./node-darwin/bin/node node-darwin/lib/node_modules/npm/bin/npm-cli.js --prefix . install --unsafe-perm --scripts-prepend-node-path
```

--------------------------------

### Update pom.xml for AEM Guides Upgrade

Source: https://experienceleague.adobe.com/en/docs/experience-manager-guides/using/release-info/release-notes/cloud-release-notes/2022-releases/release-notes-2022-9-0

Update the `<dox.version>` property in the `pom.xml` file to the specified version to upgrade your AEM Guides as a Cloud Service setup. This is a Maven configuration change required for the upgrade process.

```xml
<dox.version>2022.9.178</dox.version>
```