DocumentationCommerceAEM Assets integration Guide

Custom automatic matching

Last update: Mon Feb 09 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • User

If the default automatic matching strategy (OOTB automatic matching) is not aligned with your specific business requirements, select the custom match option. This option supports the use of Adobe Developer App Builder to develop a custom matcher application that handles complex matching logic, or assets coming from a third-party system that cannot populate metadata into AEM Assets.

Configure custom automatic matching

  1. From the Commerce Admin, navigate to Store > Configuration > ADOBE SERVICES > AEM Assets Integration.

  2. Select Custom Matcher as the matching rule.

  3. When you select this matching rule, Admin displays additional fields to configure the endpoints and the necessary authentication parameters for the custom matching logic.

workspace.json

The Adobe I/O Workspace Configuration field provides a streamlined way to configure your custom matcher by importing your App Builder workspace.json configuration file.

You can download the workspace.json file from the Adobe Developer Console. The file contains all the credentials and configuration details for your App Builder workspace.

Example workspace.json
code language-json 
{
  "project": {
    "id": "project_id",
    "name": "project_name",
    "title": "title_name",
    "org": {
      "id": "id",
      "name": "Organization_name",
      "ims_org_id": "ims_id"
    },
    "workspace": {
      "id": "workspace_id",
      "name": "workspace_name_id",
      "title": "workspace_title_id",
      "action_url": "https://action_url.net",
      "app_url": "https://app_url.net",
      "details": {
        "credentials": [
          {
            "id": "credential_id",
            "name": "credential_name_id",
            "integration_type": "oauth_server_to_server",
            "oauth_server_to_server": {
              "client_id": "client_id",
              "client_secrets": ["secret"],
              "technical_account_email": "xx@technical_account_email.com",
              "technical_account_id": "technical_account_id",
              "scopes": [
                "AdobeID",
                "openid",
                "read_organizations",
                "additional_info.projectedProductContext",
                "additional_info.roles",
                "adobeio_api",
                "read_client_secret",
                "manage_client_secrets"
              ]
            }
          }
        ],
        "services": [
          {
            "code": "AdobeIOManagementAPISDK",
            "name": "I/O Management API"
          }
        ],
        "runtime": {
          "namespaces": [
            {
              "name": "namespace_name",
              "auth": "example_auth"
            }
          ]
        },
        "events": {
          "registrations": []
        },
        "mesh": {}
      }
    }
  }
}
  1. Drag and drop your workspace.json file from your App Builder project into the Adobe I/O Workspace Configuration field. Alternatively, you can click to browse and select the file.

Workspace Configuration {width="600" modal="regular"}

  1. The system automatically:

    • Validates the JSON structure
    • Extracts and populates OAuth credentials
    • Fetches available runtime actions for the workspace
    • Populates dropdown options for the Product to Asset URL and Asset to Product URL fields

  2. Select the appropriate runtime actions from the dropdown menus for each flow.

  3. Click Save Config.

Custom matcher API endpoints

When you build a custom matcher application using App Builder, the application must expose the following endpoints:

  • App Builder asset to product URL endpoint
  • App Builder product to asset URL endpoint

App Builder asset to product URL endpoint

This endpoint retrieves the list of SKUs associated with a given asset:

Example usage

const { Core } = require('@adobe/aio-sdk')

async function main(params) {

    // Build your own matching logic here to return the products that map to the assetId
    // var productMatches = [];
    // params.assetId
    // params.eventData.assetMetadata['commerce:isCommerce']
    // params.eventData.assetMetadata['commerce:skus'][i]
    // params.eventData.assetMetadata['commerce:roles']
    // params.eventData.assetMetadata['commerce:positions'][i]
    // ...
    // End of your matching logic

    return {
        statusCode: 500,
        body: {
            asset_id: params.assetId,
            product_matches: [
                {
                    product_sku: "<YOUR-SKU-HERE>",
                    asset_roles: ["thumbnail", "image", "swatch_image", "small_image"],
                    asset_position: 1
                }
            ]
        }
    };
}

exports.main = main;

Request

POST https://your-app-builder-url/api/v1/web/app-builder-external-rule/asset-to-product
Parameter
Data Type
Description
assetId
String
Represents the updated asset ID.
eventData
String
Returns the data payload associated with the asset ID.

Response

{
  "asset_id": "{ASSET_ID}",
  "product_matches": [
    {
      "product_sku": "{PRODUCT_SKU_1}",
      "asset_roles": ["thumbnail","image"]
    },
    {
      "product_sku": "{PRODUCT_SKU_2}",
      "asset_roles": ["thumbnail"]
    }
  ]
}

App Builder product to asset URL endpoint

This endpoint retrieves the list of assets associated with a given SKU:

Example usage

const { Core } = require('@adobe/aio-sdk')

async function main(params) {
    // return asset matches for a product
    // Build your own matching logic here to return the assets that map to the productSku
    // var assetMatches = [];
    // params.productSku
    // ...
    // End of your matching logic

    return {
        statusCode: 500,
        body: {
            product_sku: params.productSku,
            asset_matches: [
                {
                    asset_id: "<YOUR-ASSET-ID-HERE>", // urn:aaid:aem:1aa1d5i2-17h8-40a7-a228-e3ur588deee1
                    asset_roles: ["thumbnail", "image", "swatch_image", "small_image"],
                    asset_format: "image", // can be "image" or "video"
                    asset_position: 1
                }
            ]
        }
    };
}

exports.main = main;

Request

POST https://your-app-builder-url/api/v1/web/app-builder-external-rule/product-to-asset
Parameter
Data Type
Description
productSKU
String
Represents the updated product SKU.
eventData
String
Returns the data payload associated with the Product SKU.

Response

{
  "product_sku": "{PRODUCT_SKU}",
  "asset_matches": [
    {
      "asset_id": "{ASSET_ID_1}",
      "asset_roles": ["thumbnail","image"],
      "asset_position": 1,
      "asset_format": image
    },
    {
      "asset_id": "{ASSET_ID_2}",
      "asset_roles": ["thumbnail"]
      "asset_position": 2,
      "asset_format": image
    }
  ]
}
Parameter
Data Type
Description
productSKU
String
Represents the updated product SKU.
asset_matches
String
Returns all assets associated with a specific product SKU.

The asset_matches parameter contains the following attributes:

Attribute
Data Type
Description
asset_id
String
Represents the updated asset ID.
asset_roles
String
Returns all available asset roles. Uses supported Commerce asset roles like thumbnail, image, small_image, and swatch_image.
asset_format
String
Provides the available formats for the asset. Possible values are image and video.
asset_position
String
Shows the position of the asset.
recommendation-more-help
62e3c486-e09f-42bb-be80-2058df1fc0e9