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.
Before setting up and using AEM with Adobe I/O, you will need to do the following:
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 ioevents-beta@adobe.com. After requesting administrative permissions, watch for an email from Adobe Systems Incorporated, as shown:
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.
To set up AEM for Adobe I/O Events:
To install the AEM Event Proxy Package:
-
Download the latest version of the package here.
-
Open AEM Package Manager by clicking the Tools icon and then clicking Deployment and Packages.
-
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.
-
Click Install.
-
On the Install Package dialog box, select Merge from the Access Control Handling drop-down list and click Install.
-
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.
-
If you are upgrading the package, delete the previous .jar file from the following location: /apps/eventproxy/install
-
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.
-
You can also manually update permissions in CRXDE Lite at the following location: /crx/de/index.jsp#/etc/cloudservices/eventproxy.
To configure OAuth and IMS authentication:
- Create a Certificate and Keystore
- Add the Keystore to the AEM eventproxy-service User Group
- Configure the AEM Link Externalizer
To create a certificate and keystore:
- 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
- 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"
-
When prompted, create an export password and store it for later use.
-
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.
- 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.
To add the key store to the AEM Eventproxy-service user group:
-
In AEM, open the User Management group by clicking the Tools icon and then clicking Security and Users.
-
On the User Management group list, click eventproxy-service to open it.
-
On Account settings, click Create KeyStore and create the key store.
-
Click Manage KeyStore and then click to expand the section for Add Private Key for Key Store file.
-
Add the keystore.p12 file by setting the key pair alias to eventproxy or the alias specified previously.
-
Provide the keystore password (the same one provided when generating the key store).
-
Provide the private key password and then provide the private key alias eventproxy.
-
Click Submit.
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 to do the following:
To create an Adobe I/O Console Integration:
-
After signing in to the Adobe I/O Console, click New Integration.
-
Select Access an API and then click Continue.
-
On the Create a new integration page, select Adobe I/O Events and then click Continue.
-
Click New integration.
-
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.
-
Click Create Integration.
To configure Adobe I/O Events as a cloud service in AEM:
-
Open the Cloud Services console, or click the Tools icon, then click Deployment and Cloud Services.
-
Under Adobe Marketing Cloud on the Cloud Services page, click Show Configurations for Adobe I/O Events.
-
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.
For all the Adobe I/O event types known to the Adobe I/O event model, you can change:
- the OSGI event topic
- the filter used in the OSGI event handler
- the default path for asset events: /content/dam
- the default path for page events: /content
The OSGI event handler intercepts the events according to these values and then maps the OSGI events to the Adobe I/O event model before forwarding them to Adobe I/O.
You can also perform advanced configuration of events through the OSGI configuration panel.
To use the panel:
-
Click the Tools icon in AEM and then click Operations and Web Console.
-
In the OSGI menu, select Configuration.
Or, simply search for: Adobe I/O Events CSM Registration.
-
For Adobe I/O Events CSM Registration, click the Edit button.
The default paths for asset and page events are listed near the top of the configuration page.
You can use the AEM Web Console Sling Health Check to verify that your configurations are correct.
To verify your configurations:
-
Check that all your configurations properly load by executing the Health Check tagged with eventproxy, conf.
-
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.
-
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.
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.
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);
You can watch the solution work by testing your integration. To do this:
Once you have your webhook ready, use the Adobe I/O Console to register it:
-
On the Adobe I/O Console, click New Integration.
-
Select Receive near-real time events and click Continue.
-
Select the AEM Link Externalizer base URL that you previously specified and then click Continue.
-
Select Create new integration and fill in the Integration Details form similar to your previous integration.
-
Click the Add webhook button and complete the Add a new webhook form.
-
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.
To perform a webhook health check:
-
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.
-
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.
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.
