Connecting SAP Commerce and AEM: Experimenting with OpenAPI-Based APIs

Some time back, I got tasked with setting up the configurable asset picker, alongside Dynamic Media's OpenAPI capabilitiess. The picker used the API to search for assets and place a delivery URL on the page. Not long after, I worked on repoless sites, which led me to the AEM Admin API. Then I saw Ian Reasor posting about updates to the Assets Author API.

It feels like Adobe is releasing more and more OpenAPI-Based APIs these days.

Around that same time, I found myself working with SAP Commerce. And I started wondering: could I connect SAP to AEM to automatically generate content fragments from product data?

This post documents what I tried—and what I learned along the way. I’ll cover how to set up SAP Commerce webhooks to send product events to an external worker process, and how to configure AEM’s Sites API so that the worker can create content fragments in response.

Set up OpenAPI-based AEM APIs

If you attempt to add an API to your ADC project, you may find you can only configure user authentication. Such as OAuth Web App credential. If Server to Server is not an option for you, you will need to take a few steps to set up OpenAPI-based AEM APIs.

1. Modernize the AEMaaCS environment.

2. Add new Product Profiles.

3. Enable AEM APIs access.

Now you will be able to add the sever-to-server credential in the ADC project. Finally, you will need to add the Client ID for the credential to the allowedClients in the api.yml file. And deploy it using the AEM configuration pipeline (via Cloud Manager). This ensures your AEM environment trusts the integration.

Under the hood, the OpenAPI is connecting to an AEM environment. And the access the API will have gets determined by the author instance Product Profiles. Luckily, the list of profiles is not too long. If you're unsure where to start, use: 'AEM Administrators - author - [Program ID] - [Environment ID]'. Then work backward from there to apply the principle of least privilege.

Create a Content Fragment Model With the Sites API

Before you can create content fragments, you need to create a content fragment model. There are two ways to created them:

1. In the tools console by going to Tools > General > Content Fragment Models

2. The Content Fragments console in the top level of the Global Navigation

The tools console is the older editor that gets deployed with the AEM environment. While the Content Fragments console is the newer cloud-based editor. Either way, when you create a content fragment model, it will get persisted to the JCR on an AEM environment. And from there you can grab it with a content package and copy it to other environments.

For this demo, we'll use the API to create the model. The first thing you will need is an OAuth access token. Locate the client id & secret found in the ADC project server-to-server credential. Then use this curl command.

Place the access_token in the Authorization header and now you can now create a model. Here is a basic model with title, description created under /conf/wknd

If you encounter an error it could be one of two things.

1. Enable content fragments in the configuration browser.

2. The technical account the lacks the necessary permissions.

In the case of permissions, you have two options

1. Update the Product profiles to one that can create/update/delete models.

2. Update the permissions of the service group on the AEM environment.

In my case, I opted for the second option. So I used the configuration browser to give the Service user group permission to manage models. Or you could have granted permissions to the technical account. But technical accounts can change. Groups will not.

The important thing to note here is that Product Profiles will only get you read access. For create, update and delete, you'll need to grant permissions on the AEM environment.

Create a Content Fragment With the Sites API

Using the same OAuth access token, you can create a content fragment with the API. Use the model id you received when you created the model. But if you don't have it, in this case, model ids are base64 encoded JCR paths. So in my example above, the model got created at /conf/wknd/settings/dam/cfm/models/my-sap-product. Its id is L2NvbmYvd2tuZC9zZXR0aW5ncy9kYW0vY2ZtL21vZGVscy9teS1zYXAtcHJvZHVjdA.

If the content fragment got created, you can move on to the next step. Otherwise if you received an access error, you'll need to grant permissions. In my case, I granted it to the Service user group through the permissions console.

Setting Up Webhooks in SAP Commerce

SAP Commerce is to SAP what AEM is to Adobe. A small part of the much larger platform. And SAP commerce is a lot like AEM. Its a Java based application. But instead of Sling, its Spring. Instead of JCR, its SQL. Instead of building marketing sites, its for e-commerce sites.

I'm not an SAP expert, so I will stick to the high-level. I will only setup what is out-of-the-box without getting into customization. I setup a local instance using the installer recipes. This installed among other things, the Power Tools reference implementation. It is the WKND project for SAP Commerce. I will use its product catalog.

Below is the ImpEx script that will configure the out-of-the-box SAP Commerce webhooks. You can do this in the Backoffice Administration cockpit. But ImpEx can get saved in source control.

The three main things this sets up are

• The integration object: An object used to map an item (in this case a Product) to a JSON payload. Other product relationships can get mapped i.e. prices, references & categories. But for this demo I am only mapping basic product properties.

• The consumed destination: Setup the destination URL. Along with a basic credential.

• The webhook configuration: This will setup the ItemSavedEvent and ItemDeletedEvent. And a filter to limit events to the Online version of the powertoolsProductCatalog.

⚠️ I am using a basic credential even though there is a Consumed OAuth Credential. I could not get it to work with Adobe IMS. In the App Builder webhoook, you will need to set require-adobe-auth to false. And then do your own basic auth check.

Once you run the ImpEx script, you can log on to the Integration UI Tool and test the webhook. Here is a short video that shows the test feature. I setup a Postman mock server to do the testing.

Implementing The Webhook

So far we have set up the OpenAPI. And verified that we can create models and fragments. The SAP webhooks have been set up and verified with a Postman mock server. The final piece in this composable architecture is a worker process. This is the nice thing about composable architecture. Your worker process can be anything anywhere. For example an Azure Function. Or an Adobe App Builder application.

Remember that I could only set up basic authentication in the SAP Commerce webhook. For my POC, I was using App Builder. So I set require-adobe-auth to false, and implemented my own check. Here is the JavaScript snippet.

Once the request gets authenticated, the next thing I needed was an OAuth token. To make API calls to the Sites API. The credential details are on the Server-to-Server credentials of the ADC project. Here is a simple JavaScript snippet to get a token

This should work on any platform. But to avoid unnecessary requests to IMS, the token should get cached and its lifetime managed. If you are using App Builder, you can use the IMS SDK Library. It uses the State SDK Library to persist the token in App Builder's cloud storage.  So that it can get used across many invocations of the runtime action.

Here is a short snippet. The first thing you need to do is set the context. And then you can call getToken anytime during the invocation of the action.

The last step would be to create/update/delete the content fragment. Here is a more complete example that handles the sap.cx.commerce.MyProductIO.Created.v1 event.

Conclusion

These OpenAPI-based APIs are well documented and intuitive—but they’re still new and not yet widely used. That makes it hard to find practical, real-world examples.

For instance, as of this writing, I’m still trying to figure out how to search for a specific content fragment by a field value (like the SKU in my example). I have a feeling it’s possible through the GraphQL API, but I’m still wrapping my head around it—and haven’t found a solid example yet.

This wasn’t a fully productionized solution, but it confirmed that with the right plumbing and some permissions wrangling, the OpenAPIs can bridge SAP and AEM in interesting ways. I’m curious to keep exploring.