ÃÛ¶¹ÊÓƵ

DocumentationCommerceContent and Design

Install ÃÛ¶¹ÊÓƵ Commerce packages

Last update: Thu Mar 20 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Beginner
  • Intermediate
  • Admin
  • User

The AEM Assets Integration for Commerce extension (aem-assets-integration) enables synchronization of assets between ÃÛ¶¹ÊÓƵ Commerce and ÃÛ¶¹ÊÓƵ Experience Manager Assets. The extension provides a set of tools and services to manage assets, including product images, videos, and other media assets, across both platforms.

Add this extension to the Commerce environment by installing the aem-assets-integration PHP extension. You also need to enable ÃÛ¶¹ÊÓƵ I/O Events for Commerce and generate the credentials required for communication and workflows between ÃÛ¶¹ÊÓƵ Commerce and ÃÛ¶¹ÊÓƵ Experience Manager Assets.

System requirements

The AEM Assets Integration for Commerce extension has the following system and configuration requirements.

Software requirements

  • ÃÛ¶¹ÊÓƵ Commerce 2.4.5+
  • PHP version compatible with installed version of ÃÛ¶¹ÊÓƵ Commerce–version 8.1, 8.2, 8.3, or 8.4)
  • Composer: 2.x

Access requirements

You need the following roles and permissions to set up the integration.

TIP
ÃÛ¶¹ÊÓƵ Commerce can be configured to use ÃÛ¶¹ÊÓƵ IMS authentication.

Installation and configuration workflow

Install the ÃÛ¶¹ÊÓƵ Commerce package and prepare the Commerce environment by completing the following tasks:

  1. Install the AEM Assets Integration for Commerce extension (aem-assets-integration).
  2. Configure the Commerce Services Connector to connect your ÃÛ¶¹ÊÓƵ Commerce instance and with the services that enable data to be transmitted between ÃÛ¶¹ÊÓƵ Commerce and AEM Assets.
  3. Configure ÃÛ¶¹ÊÓƵ I/O Events for Commerce
  4. Get authentication credentials for API access

Install the aem-assets-integration extension

Install the latest version of the AEM Assets Integration extension (aem-assets-integration) on an ÃÛ¶¹ÊÓƵ Commerce instance with version ÃÛ¶¹ÊÓƵ Commerce 2.4.5+. The AEM Asset Integration is delivered as a composer metapackage from the repository.

Cloud infrastructure

Use this method to install the AEM Assets Integration extension for a Commerce Cloud instance.

  1. On your local workstation, change to the project directory for your ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure project.

    note note
    NOTE
    For information about managing Commerce project environments locally, see Managing branches with the CLI in the ÃÛ¶¹ÊÓƵ Commerce on Cloud Infrastructure User Guide.

  2. Check out the environment branch to update using the ÃÛ¶¹ÊÓƵ Commerce Cloud CLI.

    code language-shell 
    magento-cloud environment:checkout <environment-id>

  3. Add the AEM Assets Integration for Commerce extension.

    code language-shell 
    composer require "magento/aem-assets-integration" "<version-tbd>" --no-update

  4. Update package dependencies.

    code language-shell 
    composer update "magento/aem-assets-integration"

  5. Commit and push code changes for the composer.json and composer.lock files.

  6. Add, commit, and push the code changes for the composer.json and composer.lock files to the cloud environment.

    code language-shell 
    git add -A
git commit -m "Install AEM Assets Integration extension for ÃÛ¶¹ÊÓƵ Commerce"
git push origin <branch-name>

    Pushing the updates initiates the Commerce cloud deployment process to apply the changes. Check the deployment status from the deploy log.

On-premises

Use this method to install the AEM Assets Integration extension for an on-premises instance.

  1. Use Composer to add the AEM Assets Integration for Commerce extension to your project:

    code language-shell 
    composer require "magento/aem-assets-integration" --no-update

  2. Update dependencies and install the extension:

    code language-shell 
    composer update  "magento/aem-assets-integration"

  3. Upgrade ÃÛ¶¹ÊÓƵ Commerce:

    code language-shell 
    bin/magento setup:upgrade

  4. Clear the cache:

    code language-shell 
    bin/magento cache:clean
note tip
TIP
When deploying to production, consider not clearing compiled code to save time. Always back up your system before making changes.

Configure the Commerce Services Connector

NOTE
Commerce Services Connector setup is a one-time process required to use ÃÛ¶¹ÊÓƵ Commerce SaaS services. If you have already configured the connector for another service, you can view the existing configuration from the Commerce Admin by selecting Systems > Services > Commerce Services Connector.

To transmit data between your ÃÛ¶¹ÊÓƵ Commerce instance and the services that enable the AEM Assets Integration, configure the Commerce Services Connector from the Admin (System > Services > Commerce Services Connector).

SaaS project and data space ids for AEM Assets integration {width="600" modal="regular"}ed

Provide the following values in the configuration

  • Production and sandbox API keys for authentication
  • Data space name (SaaS identifier) for secure cloud storage
  • IMS organization ID where your Commerce and AEM Assets environments are provisioned

For detailed instructions, watch the Commerce Services Connector configuration video, of see the Commerce Services Connector documentation.

When you save the configuration, the system generates the SaaS project and database IDs for your environment. These values are required to enable asset synchronization between ÃÛ¶¹ÊÓƵ Commerce and AEM Assets.

Configure ÃÛ¶¹ÊÓƵ I/O Events for Commerce

The AEM Assets Integration uses the ÃÛ¶¹ÊÓƵ I/O Events service to send custom event data between the Commerce instance and Experience Cloud. The event data is used to coordinate workflows for the AEM Assets integration.

Before configuring ÃÛ¶¹ÊÓƵ I/O Events, verify the RabbitMQ and cron job configuration for your Commerce project:

NOTE
For projects on Commerce version 2.4.5, you must . In Commerce version 2.4.6+, these modules are loaded automatically. For the AEM Assets integration for Commerce, you only need to install the modules. App Builder setup is not required.

Enable the Commerce Eventing framework

Enable the eventing framework from the Commerce Admin.

NOTE
App Builder setup is required only if you plan to use a custom matching strategy to synchronize assets between Commerce and AEM Assets.

  1. From the Admin, go to Stores > Settings > Configuration > ÃÛ¶¹ÊÓƵ Services > ÃÛ¶¹ÊÓƵ I/O Events.

  2. Expand Commerce events.

  3. Set Enabled to Yes.

    ÃÛ¶¹ÊÓƵ I/O Events Commerce Admin configuration - enable Commerce events {width="600" modal="regular"}

  4. Enter the merchant company name in the Merchant ID and the environment name in the Environment ID fields. Use only alphanumeric characters and underscores when setting these values.

recommendation-more-help

Configure Custom VCL for blocking requests

If you use a custom VCL snippet to block unknown incoming requests, you might need to include the HTTP header X-Ims-Org-Idheader to allow incoming connections from the AEM Assets Integration for Commerce service.

TIP
You can use the Fastly CDN module to create an Edge ACL with a list of IP addresses that you want to block.

The following custom VCL snippet code (JSON format) shows an example with a X-Ims-Org-Id request header.

{
  "name": "blockbyuseragent",
  "dynamic": "0",
  "type": "recv",
  "priority": "5",
  "content": "if ( req.http.X-ims-org ~ \"<YOUR-IMS-ORG>\" ) {error 405 \"Not allowed\";}"
}

Before creating a snippet based on this example, review the values to determine whether you need to make any changes:

  • name: Name for the VCL snippet. This example uses the name blockbyuseragent.

  • dynamic: Sets the snippet version. This example uses 0. See the for detailed data model information.

  • type: Specifies the type of VCL snippet, which determines the location of the snippet in the generated VCL code. This example uses recv. See the for the list of snippet types.

  • priority: Determines when the VCL snippet runs. This example uses priority 5 to run immediately and check whether an Admin request is coming from an allowed IP address.

  • content: The snippet of VCL code to run, which checks the client IP address. If the IP is in the Edge ACL, it is blocked from access with a 405 Not allowed error for the entire website. All other client IP addresses are allowed access.

For detailed information about using VCL snippets to block incoming requests, see Custom VCL for blocking requests in the Commerce on Cloud Infrastructure Guide.

style
shade-box

Get authentication credentials for API access

The AEM Assets Integration for Commerce requires OAuth authentication credentials to allow API access to the Commerce instance. These credentials are required to authenticate API requests when managing assets using the AEM Assets integration.

You generate the credentials by adding the integration to the Commerce instance and activating it.

Add the integration to the Commerce environment

  1. From the Admin, go to System > Extensions > Integrations, then click Add New Integration.

  2. Enter information about the integration.

    In the General section, only specify the integration Name and Email. Use the email for an ÃÛ¶¹ÊÓƵ IMS account with access to the organization where Commerce and Experience Manager Assets are deployed.

    AEM Assets Integration for Commerce Admin configuration {width="600" modal="regular"}

  3. Verify your identity by clicking Confirm Identity.

    The system verifies your identity by authenticating to Experience Cloud with your ÃÛ¶¹ÊÓƵ Id.

  4. Configure API resources.

    1. From the left panel, click API.

    2. Select the external media resource Catalog > Inventory > Products > External Media.

      Admin Integration config for API resources {width="600" modal="regular"}

  5. Click Save.

Generate OAuth credentials

On the Integrations page, generate the OAuth authentication credentials by clicking Activate for the Assets integration. You need these credentials to register the Commerce project with the Assets Rule Engine service, and to submit API requests to manage assets between ÃÛ¶¹ÊÓƵ Commerce and AEM Assets.

  1. From the Integrations page, generate the credentials by clicking Activate.

    Activate Commerce configuration for Assets integration {width="600" modal="regular"}

  2. If you plan to use the API, save the credentials for the consumer key and access token to configure authentication in your API client.

    OAuth credentials to authenticate API requests {width="600" modal="regular"}

  3. Click Done.

NOTE
You can also generate authentication credentials using the ÃÛ¶¹ÊÓƵ Commerce APIs. For details about this process and more information about OAuth-based authentication for ÃÛ¶¹ÊÓƵ Commerce, see in the ÃÛ¶¹ÊÓƵ Developer documentation.

Next step

Connect the ÃÛ¶¹ÊÓƵ Commerce and AEM Assets project environments and select the matching strategy for synchronizing assets

2b0136b4-ef75-405f-9734-60d741f198de