AEM Project Setup

This tutorial covers the creation of a Maven Multi Module Project to manage the code and configurations for an Adobe Experience Manager Site.

Prerequisites

• Instance of Adobe Experience Manager available locally.
• java 7+
• maven

We will generate a new Adobe Experience Manager project using the AEM Project Archetype . Your AEM project contains all of the code, content, and configurations used for a Sites implementation.

What is a Maven project? - Apache Maven is a software management tool to build projects. All Adobe Experience Manager implementations use Maven projects to build, manage and deploy custom code on top of AEM.

What is a Maven archetype? - A Maven archetype is a template or pattern for generating new projects. The AEM Project archetype allows us to generate a new project with a custom namespace and include a project structure that follows best practices, greatly accelerating our project.

Create the project

We use version 22 of the archetype. However, it is always a best practice to use the latest version of the archetype to generate a new project.

The next series of steps are:

Step 1: Open command prompt and check maven is installed correctly.

Step 2: Verify that the adobe-public profile is active by running the following command:

Success if adobe-public is active.

If you do not see the adobe-public it is an indication that the Adobe repo is not properly referenced in your ~/.m2/settings.xml file. Please revisit the steps to install and configure Apache Maven in a local development environment .

Step 3: Navigate to a directory in which you want to generate the AEM project.  and run below maven command.

mvn archetype:generate -B \

  -DarchetypeGroupId=com.adobe.granite.archetypes \

  -DarchetypeArtifactId=aem-project-archetype \

  -DarchetypeVersion=22 \

  -DgroupId=com.adobe.aem.guides \

  -Dversion=0.0.1-SNAPSHOT \

  -DappsFolderName=asc \

  -DartifactId=aem-guides-asc \

  -Dpackage=com.adobe.aem.guides.asc \

  -DartifactName="ASC Sites Project" \

  -DcomponentGroupName=ASC \

  -DconfFolderName=asc \

  -DcontentFolderName=asc \

  -DcssId=asc \

  -DisSingleCountryWebsite=n \

  -Dlanguage_country=en_us \

  -DoptionAemVersion=6.5.0 \

  -DoptionDispatcherConfig=none \

  -DoptionIncludeErrorHandler=n \

  -DoptionIncludeExamples=y \

  -DoptionIncludeFrontendModule=y \

  -DpackageGroup=asc \

  -DsiteName="ASC Site"

It will scan and create project in specified directory.

Step 4: You can go the directory and can look below project structure.

For above used properties refer detail here  https://experienceleague.adobe.com/docs/experience-manager-core-components/using/developing/archetype/overview.html?lang=en

Build the project:

Step 1: Go to project: cd aem-guides-asc

Step 2: Run the following command to build and deploy the entire project to AEM:

   mvn clean install -PautoInstallPackage

Note: Please start AEM instance first before running AEM deploy command.

You can run below command to deploy code on AEM publish instance. You can refer parent pom.xml for the same and also README.md file which has all instructions to deploy code.

Step 3: Navigate to the Sites console: http://<host>:<port>/sites.html/content for e.g. if your instance is running on 4502 then open below url in browser and login with username/password. Default credentials would be admin/admin.

http://localhost:4502/sites.html/content .

Open any page from project and if it working fine then we are done!

Congratulations! Your project is set up now.

Handle ACL via Pom

In this blog, we are going to handle ACL via pom.xml of the project.

ACL available options:

• ignore
• overwrite
• merge
• merge_preserve
• clear

By default acls are installed in overwrite mode.

You can add any of the option in pom file. Below is the code for "merge" ACL option via pom:

Debugging in AEM and IDE

In this tutorial, we will first start AEM in debug mode and add remote debug connection in IDE(IntelliJ).

What is Debugging?

It is a systematic process of spotting and fixing the number of bugs, or defects, in a piece of software so that the software is behaving as expected. 

Debugging refers to identifying, analyzing, and removing errors. It is considered to be an extremely complex and tedious task because errors need to be resolved at all stages of debugging. 

When we work in IDE then we need to debug code to find or check what data is capturing.

We normally work on IntelliJ or Eclipse in the AEM project.

There are multiple ways to start AEM in debug mode.

Step 1: Add the Remote Debugging JVM Parameter

Start AEM with this JVM parameter

-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n

Another way to launch AEM instance in debug mode: 

Include it as a parameter when starting AEM with java -jar directly.

 java -Xmx512m -agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n -jar cq-author-4502.jar

Another way to start AEM in debug mode, do changes in start.bat file for windows. 

For Windows Users

• Go to <AEM-Install>\crx-quickstart\bin
• Open start.bat file
• Go to line #25

You can see line content is:

if not defined CQ_JVM_OPTS set CQ_JVM_OPTS=-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true

Append below content to end of this line #25

You can see line content is:

if not defined CQ_JVM_OPTS set CQ_JVM_OPTS=-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true

Append below content to end of this line #25

-debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=<port>

You can use the below line directly. I am using address 30303. You can map to any available port.

if not defined CQ_JVM_OPTS set CQ_JVM_OPTS=-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true -debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303

• Save start.bat file.
• Start AEM now. Double click to start.bat to run your AEM instance.

For Mac users:

You can use the below line in start.sh directly in Mac OS. -z means zero length. for example, if [ -z "$CQ_JVM_OPTS" ]; then means if $CQ_JVM_OPTS is empty. 

if [ -z "$CQ_JVM_OPTS" ]; then
	CQ_JVM_OPTS='-server -Xmx2048m -XX:MaxPermSize=256M -Djava.awt.headless=true -agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n'
	...
fi

• Start AEM instance using start.sh on Mac OS.

The server is now running in debug mode.

Step 2: Debugging in IDE- IntelliJ

Open Project in IntelliJ Go to 

Run > Debug

After that below pop-up will appear

Click Edit Configurations.

The below screen will appear on clicking "Edit configurations".

Click "+" to add a new configuration. Select "Remote"

The below screen will appear on selecting Remote.

Enter below configurations:

Name: You can add any name. I want to debug on my local AEM author instance so I used localhost-author.

Host: IP address on which AEM instance is running. If it is running on the local machine then use "localhost".

Port: Enter port number on which you have configured debug address. In my case it is "

30303". You can refer #1 to check your debug port. I used below command to set up debug address:

if not defined CQ_JVM_OPTS set CQ_JVM_OPTS=-Xmx1024m -XX:MaxPermSize=256M -Djava.awt.headless=true -debug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303

Note: Command-line arguments automatically changed.

Module: Select module to debug. You can select any module for debugging or directly your project name. I have selected "Core" as my java classes are in the core module.

Click Apply and Debug.

Testing:

Select the java file which you want to debug.

Add a breakpoint to line

from UI, Hit the respective URL.

You can see, your file is in debug mode.

Congratulations!!! Your AEM instance is running in debug mode and can debug in IDE.

Integrating SOLR with Adobe Experience Manager 6.5

In this tutorial, we will integrate Apache Solr with AEM.

Introduction

Solr is an open-source enterprise-search platform, written in Java, from the Apache Lucene project. Solr is the popular, blazing-fast, open-source enterprise search platform built on Apache Lucene. Solr is highly reliable, scalable, and fault-tolerant, providing distributed indexing, replication, and load-balanced querying, automated fail-over and recovery, centralized configuration, and more. Solr powers the search and navigation features of many of the world's largest internet sites.

Major features:

• full-text search
• hit highlighting
• faceted search
• real-time indexing
• dynamic clustering
• database integration
• NoSQL features
• rich document handling.

Setup the Solr Server

Step 1: To install Solr server, you need to have Java 1.8 installed.  

Step 2: Download and install the Solr server (solr-6.2.0.zip ) from the following URL:

http://archive.apache.org/dist/lucene/solr/

Step 3: Unzip the zip file.

Step 4: After unzipping file structure of solr seems like

Step 5: Go to the bin folder and run the below command to start the Solr server. 

solr start -e cloud -noprompt

Step 6: Once the server starts, you will see the message in the command prompt. Solr is started on 8983 port.

Step 7: Open the browser and verify the URL

http://localhost:8983/solr/#/

You can see solr web client.

Step 8: Download the code from GitHub. Unzip it some directory. You can directly clone this project. Follow below command:

git clone https://github.com/heenamadan/AemSolr2.git

Step 9: Go to the AemSolr2 folder and run below the maven command to deploy code.

Step 10: Now go to solr web client and create a collection:

This collection is for a single search index. Follow the below steps to create an index in solr.

From the web client, select Collection

Click Add Collection

provide the name of the collection "collection".

Choose the config list from dropdown. I am using gettingstarted.

You can provide a shard number according to your requirement. I am keeping it 1 at this moment.

You can provide a replication factor. By default, it is 1.

Click add a collection. You can see the collection is created.

There are a lot of options available like you can delete collection by clicking the "Delete" button or you can also create an alias. We are just creating collection as part of this article.

We are done at solr side. Now we will do some configurations at the AEM side.

Step 11: Configure AEM to Solr:

• Go to localhost:4502/system/console/bundles
• Select configuration from bundles tab
• Or directly go to link localhost:4502/system/console/configMgr

1) Search for "AEM Solr Search - Solr Configuration" service and enter the  following values:

    Protocol: http

    Solr Server Name: localhost

    Solr Server Port: 8983 (port number of your solr web client)

    Solr Core Name: collection ( references the collection you created)

    Content page path: /content/AemSolr2

Note: Provided code base(download from Github) has a content site structure under AemSolr2. You can provide any site structure path here for indexing. 

2) Search "Oak Solr remote" in configuration and check solr details. Check the port number of solr in the Solr HTTP URL. The rest is fine. Click Save.

3) Search "oak solr server provider" and select remote solr from the drop-down.

As our Solr is installed separately, It is not embedded so select "Remote Solr"

Now we are good to go!

Now create an index in Solr. For this, we have IndexContentToSolr java servlet which makes a connection to solr and creates an index.

For code brevity, this code example uses repository.loginAdministrative(null) method. This is used simply to keep the code shorter. If you are using this in Production, the recommended way is to create a system user and use the Sling Mapping Service. In order to run this example without creating system user, you can whitelist this call. It is not recommanded to use this. Please create appropriate system user and use sling mapping.

To Bypass login request, enable bypass. Go to configMgr Search "Sling Login Admin whitelist" and click the checkbox and save. ( for testing purpose only)

 

 

 For UI, I have created a basic component that is used to create indexing and delete indexing. Open http://localhost:4502/apps/AemSolr2/solr-index/components/content/solr-config.html

Click the "Index Pages" button. The default value is already populated to the text field which is "indexpages". Pages are successfully indexed.

Response Message: "Response is successfully indexed pages to solr server".

Index creation is done on the properties that you specified in your java file. For example, we did on below properties only. It will do indexing on id, title, etc. properties that we have added to create an index if present in page properties.

Check solr web client to check indexes. Click collection Selection drop down from the left panel and select your collection name. In our case, it is "collection"

Now Select Query from the left panel and click execute a query. 

All indexed pages appear as a result.

You can see the results. We have 3 pages and all got indexed with properties on which we have applied indexing.

Or you can check by directly going through this link and click execute the query.

View Solr results in AEM

In the codebase, we have a component named "solrsearch". Go to  /apps/AemSolr2/components/content/solrsearch to see component details.

Add below lines on top of the HTML file of /apps/AemSolr2/components/content/solrsearch/solrsearch.html

<script src="https://code.jquery.com/jquery-3.1.0.js" integrity="sha256-slogkvB1K3VOkzAI8QITxV3VzpOnkeNVsKvtkYLMjfk=" crossorigin="anonymous"></script>  

I have already added this line to my component.

Now open any page for eg. http://localhost:4502/editor.html/content/AemSolr2/en.html. Click to drag component. You will see the "+" icon to add a component. 

Search the "Solr Search" and Add component.

Open in preview/publish view.

Now search with the title of the page. for eg: "heena"

Below is the result.

Search with "Francais" below is the result.

Now I am searching with id-"en". It shows the result.

It searched with "like" operator. So you type complete id "/content/AemSolr2/en.html" then it will show all results which have the same pattern.

Now I am trying with a random string that is not indexed.

Congratulations!!

Search is working in AEM with apache solr.👍

You can search in apache solr to check the result is the same as AEM search or not.

Go to solr web client and in the query enter title/id etc. on which you want to apply search and click execute the search. Let's search for "English" and the only title which has "English" keyword has appeared as a result.

Enter "English" in q place which is query string place.

You can delete the index that you have created earlier. Click "Delete index" to the component and you are done.

Index Deleted in Solr web server.

Stop the Solr server. Go to the bin folder of Solr and Run solr stop -all command.