Set up AEM for Adobe I/O Events

These instructions describe how to set up Adobe Experience Manager (AEM) for Adobe I/O Events. You can use Adobe I/O for notification of AEM events, such as page or asset changes.

1. Introduction

2. Set Up Products

3. Use Adobe I/O

4. Watch the Solution Work

Introduction

Before setting up and using AEM with Adobe I/O, you will need to do the following:

1. Obtain Authorization

2. Register an AEM Event Consumer App

Obtain Authorization

To complete this solution, you will need authorization to use the following services:

• AEM instance with version 6.2 or 6.3, with administrative permissions

• Adobe I/O Console access, with administrative permissions for your enterprise organization. If you do not have administrative permissions, please contact [email protected]. After requesting administrative permissions, watch for an email from Adobe Systems Incorporated, as shown:

  

Register an AEM Event Consumer App

You will need to register an AEM event consumer app, such as a webhook, to see responses to AEM changes. These instructions include steps for setting up a webhook that is able to accept and reply to a challenge http request parameter sent by Adobe I/O Channel & Subscription Management (CSM). For more information on understanding and working with webhooks, see the Introduction to Adobe I/O Events Webhooks.

Set Up Products

To set up AEM for Adobe I/O Events:

1. Install the AEM Event Proxy Package

2. Configure OAuth and IMS Authentication

Install the AEM Event Proxy Package

To install the AEM Event Proxy Package:

1. Download the latest version of the package here.

2. Open AEM Package Manager by clicking the Tools icon and then clicking Deployment and Packages.

   

3. In Package Manager, click Upload Package. Click the Browse button and navigate to the package zip file. Click OK.

Note: If you have an older version of the package, delete it to avoid potential conflicts. You can delete it from the following location: crx/de/index.jsp#/apps/eventproxy/install.

4. Click Install.

   

5. On the Install Package dialog box, select Merge from the Access Control Handling drop-down list and click Install.

   

6. Watch the Activity Log. If installed, the log reports that the package is imported.

   

For more information on installing packages in AEM, see How to Work with Packages.

Additional Package Installation Notes

1. If you are upgrading the package, delete the previous .jar file from the following location: /apps/eventproxy/install

2. Verify that the Access Control Handling is properly applied by checking permissions for the eventproxy-service user group at /useradmin. If applied correctly, the eventproxy-service user is added to the following:

• /home/users/system/eventproxy/eventproxy-service with jcr:read and rep:write authorizations
• /etc/cloudservices/eventproxy with jcr:read and rep:write authorizations
• /content with jcr:read authorization

For more information, see AEM User, Group and Access Rights Administration.

3. You can also manually update permissions in CRXDE Lite at the following location: /crx/de/index.jsp#/etc/cloudservices/eventproxy.

   

Configure OAuth and IMS Authentication

To configure OAuth and IMS authentication:

1. Create a Certificate and Keystore
2. Add the Keystore to the AEM eventproxy-service User Group
3. Configure the AEM Link Externalizer

Create a Certificate and Keystore

To create a certificate and keystore:

1. Create an RSA private/public certificate in OpenSSL with the following command:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout private.key -out certificate_pub.crt

2. Add the private key and signed certificate to a PKCS#12 file with the following command:

openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -export -in certificate_pub.crt -inkey private.key -out author.pfx -name "author"

3. When prompted, create an export password and store it for later use.

4. Create a keystore from the generated keys with the following command:

cat private.key certificate_pub.crt > private-key-crt

Note: On Windows systems, you may need to concatenate the files manually or provide an alternate command. For more information, see the OpenSSL manpages.

5. Set the alias as eventproxy and a non-empty keystore password (such as admin), with the following command:

openssl pkcs12 -export -in private-key-crt -out keystore.p12 -name eventproxy -noiter -nomaciter

Note: On Windows systems, this command expression may vary. For more information, see the OpenSSL manpages.

Add the Keystore to the AEM eventproxy-service User Group

To add the key store to the AEM Eventproxy-service user group:

1. In AEM, open the User Management group by clicking the Tools icon and then clicking Security and Users.

   

2. On the User Management group list, click eventproxy-service to open it.

   

3. On Account settings, click Create KeyStore and create the key store.

4. Click Manage KeyStore and then click to expand the section for Add Private Key for Key Store file.

5. Add the keystore.p12 file by setting the key pair alias to eventproxy or the alias specified previously.

6. Provide the keystore password (the same one provided when generating the key store).

7. Provide the private key password and then provide the private key alias eventproxy.

8. Click Submit.

   

Configure the AEM Link Externalizer

The AEM Link Externalizer name can be author or any other alias specified in the Adobe Experience Manager Web Console.

Note: Do not use only the word “localhost” as the default name because others may use it. This will then cause confusion and make it difficult to determine which instance is yours.

The base url that you specify appears on the AEM Web Console.

Use Adobe I/O

Use Adobe I/O to do the following:

1. Create an Adobe I/O Console Integration

2. Configure Adobe I/O Events as a Cloud Service in AEM

3. Configure Advanced Adobe I/O Events

Create an Adobe I/O Console Integration

To create an Adobe I/O Console Integration:

1. After signing in to the Adobe I/O Console, click New Integration.

2. Select Access an API and then click Continue.

   

3. On the Create a new integration page, select Adobe I/O Events and then click Continue.

   

4. Click New integration.

   

5. On the Create a new integration dialog box, specify a name for the integration and add a description. To add Public keys certificates, click Select a File and navigate to your certificate_pub.crt to upload it.

   

6. Click Create Integration.

Configure Adobe I/O Events as a Cloud Service in AEM

To configure Adobe I/O Events as a cloud service in AEM:

1. Open the Cloud Services console, or click the Tools icon, then click Deployment and Cloud Services.

   

2. Under Adobe Marketing Cloud on the Cloud Services page, click Show Configurations for Adobe I/O Events.

   

3. Configure the service by specifying each field in the Edit Component dialog box. You can copy your credentials from the Adobe I/O Console and paste them into each required field.

• For AEM Link externalizer: specify author (or any other alias previously configured in the AEM Link Externalizer).

• For API key: Provide the key shown on the Integration Details page of the Adobe I/O Console.

• For Technical Account ID: Provide the ID shown on the Adobe I/O Console.

• For Organization ID: Provide the ID shown on the Adobe I/O Console.

• For Client Secret: Click the Retrieve client secret button on the Integration Details page of the Adobe I/O Console and provide the secret as shown on the console.

  

Perform an AEM Health and Configuration Check

You can use the AEM Web Console Sling Health Check to verify that your configurations are correct.

To verify your configurations:

1. Check that all your configurations properly load by executing the Health Check tagged with eventproxy, conf.

   

2. Check that the AEM instance is able to exchange JWT tokens with Adobe I/O Identity Management System (IMS). To do this, execute the Health Check tagged with eventproxy,ims. This verifies that your IMS related configurations are correct and working, including the eventproxy-service user Keystore configuration, the Adobe I/O console-originated API key, the Technical Account ID, the Organization ID and the client secret.

   

3. Check that the event metadata and the provider associated with the AEM instance are registered in Adobe I/O Channel & Subscription Management (CSM) by executing the Health Check tagged with eventproxy,csm. This verifies that the AEM instance is successfully registered as an event provider with Adobe I/O CSM.

   

Register an AEM Event Consumer App

To register an AEM event consumer App, you can set up a webhook. Your webhook should be able to accept and reply to a challenge http request parameter sent by Adobe I/O CSM.

Set up Webhook: Example

To create a webhook at webtask.io, add the following code to make sure the Challenge is echoed back. This is needed for the verification by Adobe I/O CSM when we register the webhook URL later using CSM API:

var express = require('express');
var Webtask = require('webtask-tools');
var bodyParser = require('body-parser');
var app = express();

app.use(bodyParser.json());
app.get('/webhook', function (req, res) {
   var result = "No challenge";
   if (req.query["challenge"]){
      result = req.query["challenge"]
      console.log("got challenge: " + req.query["challenge"]);
   } else {
      console.log("no challenge")
   }
   res.status(200).send(result)
});

app.post('/webhook', function (req, res) { 
   console.log(req.body)
   res.writeHead(200, { 'Content-Type': 'application/text' });
   res.end("pong");
});

module.exports = Webtask.fromExpress(app);

Watch the Solution Work

You can watch the solution work by testing your integration. To do this:

1. Register Your Webhook with the Adobe I/O Console
2. Perform a Webhook Health Check

Register Webhook with the Adobe I/O Console

Once you have your webhook ready, use the Adobe I/O Console to register it:

1. On the Adobe I/O Console, click New Integration.

2. Select Receive near-real time events and click Continue.

   

3. Select the AEM Link Externalizer base URL that you previously specified and then click Continue.

   

4. Select Create new integration and fill in the Integration Details form similar to your previous integration.

5. Click the Add webhook button and complete the Add a new webhook form.

6. Select the events you want to subscribe to and click Save.

   

Note: Once you have registered your webhook, responses will include a status field to show if it is VERIFIED.

Perform a Webhook Health Check

To perform a webhook health check:

1. Check that events are sent to and received by Adobe I/O Event receiver (the AEM ingress adapater). To do this, execute the Health Check tagged with eventproxy, eventreceiver.

   

You can also emit a custom osgi event sample by triggering the Health Check tagged with eventproxy, custom.

2. Test the Webhook Subscription by doing the following:

   • by publishing or unpublishing AEM pages
   • by editing, adding, or removing an asset in the AEM DAM or by using the AEM Assets HTTP API

   The responses appear in your webhook.

   

   

Optional :Adobe I/O Events' OSGI to XDM Event Mapping Configurations

For all Adobe I/O event types defined by the Adobe I/O Event Model, there is an Adobe I/O Events OSGI to XDM Event Mapping Configuration.

For each of these you can change/edit:

• The OSGI Topic you want to observe: osgiTopic
• The OSGI Filter you want to apply in your osgi event observation. If left empty no osgi filtering is done: osgiFilter
• The JCR osgiJcrPathFilter to filter the OSGI events further. If left empty, no resource path filtering is done: osgiJcrPathFilter
• The OSGI Event Handler Type (use the default com.day.cq.dam.eventproxy.service.impl.listener.AdobeIoEventHandler to map any custom osgi event): osgiEventHandlerClassName
• The Adobe I/O XDM Event Type to map to the OSGI event, again, use the default (com.adobe.xdm.event.OsgiEmittedEvent) to map your custom osgi events : adobeIoXdmEventClassName
• The Adobe I/O Event Code (unique to your Event provider, i.e. unique to your AEM instance/cluster): adobeIoEventCode
• The Adobe I/O Event Label as it will appear on the Adobe I/O Console: adobeIoEventLabel

The various OSGI event handler will intercept the events according to these values and then map these OSGI events to the Adobe I/O Event Model before forwarding them to Adobe I/O.

The solution leverages the OSGI configuration factory pattern, hence not only can you edit these configurations, but you can also remove and add such configurations.

To configure using the panel:

1. Click the Tools icon in AEM and then click Operations and Web Console.

   

2. In the OSGI menu, select Configuration.

   and search for: Adobe I/O Events CSM Registration.

3. For Adobe I/O Events OSGI to XDM Event Mapping Configurationn, click the +, Edit, or Delete buttons.

Authors

• Sarah Xu @sarahxxu.
• John Wight @johnwight.

Feedback?

Please help make this solution as useful as possible. If you find a problem in the documentation or have a suggestion, click the Issues tab on this GitHub repository and then click the New issue button. Provide a title and description for your comment and then click the Submit new issue button.