Blackbird AEM Connector

Blackbird AEM Connector – OpenAPI 3.0

The YAML specification included in the documentation follows the OpenApi 3.0 standard and is designed to be compatible with Swagger UI and other OpenAPI tools.

You can paste this YAML directly into tools like Swagger Editor or integrate it into an internal API portal for interactive exploration

Prerequisites

Even though this repository is public, GitHub requires authentication to download packages from GitHub Packages, including for Maven dependencies. This is a security feature to prevent anonymous abuse of GitHub's infrastructure.

For the on-premise version, follow the steps from the instruction to embed BB AEM Connector to a project or download the latest version and install it through Package Manager manually.

For AEMaaCS version, follow the next steps to generate a token and configure Maven to use it:

Step 1: Create a GitHub Personal Access Token (PAT)

1.1 Open the Token Generator

Generate a new token (classic) with the read:packages scope

1.2 Configure the Token

• Note: Maven Access Token
• Expiration: Choose 30 days, 90 days, or No expiration
• Scope:
  • read:packages (only this is needed)

This token will only allow read access to published packages, and cannot modify repositories or access private code.

1.3 Click "Generate Token"

Copy the token immediately — you won’t be able to see it again.

Step 2: Configure Maven to Use the Token

2.1 Add to settings.xml

Create a file in your repository called settings.xml (or modify the current one) in your AEM as a Cloud Service git repository. The path for this file should be .cloudmanager/maven/settings.xml: Add the following block:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
  <servers>
    <server>
      <id>bb-io-AEM-github</id>
      <username>GITHUB_USERNAME</username>
      <password>PASTE_YOUR_PAT_HERE</password>
    </server>
  </servers>
</settings>

2.2 Replace:

• GITHUB_USERNAME with your GitHub username
• PASTE_YOUR_PAT_HERE with the token you just generated

Step 3: Add the Repository in your root pom.xml

<repositories>
    <repository>
        <id>bb-io-AEM-github</id>
        <url>https://maven.pkg.github.com/bb-io/AEM</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Step 4: Add the Dependency in your root pom.xml

4.1 Update pom.xml with

<dependency>
  <groupId>io.blackbird</groupId>
  <artifactId>bb-aem-connector.all</artifactId>
  <type>zip</type>
  <version>{current_version}</version>
</dependency>

4.2 Replace placeholder {current_version} with the latest version.

Step 5: Add the Dependency in your /all/pom.xml

<dependency>
    <groupId>io.blackbird</groupId>
    <artifactId>bb-aem-connector.all</artifactId>
    <type>zip</type>
</dependency>

Step 6: Add the package as an embedded dependency to your /all/pom.xml

<embedded>
  <groupId>io.blackbird</groupId>
  <artifactId>bb-aem-connector.all</artifactId>
  <type>zip</type>
  <target>/apps/bb-vendor-packages/application/install</target>
</embedded>

NOTE: Add path /apps/bb-vendor-packages/application/install to filter.xml for all module or change target path for the embed.

Step 7: Commit all the changes to the branch and push the changes

Step 8: The build for AEM as a Cloud Service can now be done

Configure Authorization (JWT)

Follow the official documentation to create a Technical Account for the needed AEM Author program or use the next steps.

Steps to create Technical Account

1. Open Cloud Manager.
2. Select needed program.
3. Open Developer Console for needed Author environment.
4. Switch to Integrations tab and Create new technical account.
5. Unfold created private key and View the data.
6. Use the Download button to obtain the raw data and store it in a file or another location from which it will be used for integration.

Validate integration

To validate the integration, code samples for different programming languages can be used (GitHub link).