In some of our previous articles, we have made a passing reference to the Sling runmodes property; I have found upon occasion that there are Adobe Experience Manager developers and admins out there who don’t fully understand how these work. I am not going to go into all the information about runmodes—we will have a future series of articles from one of our Systems Engineers that will guide you through all of that. However, I’d like to at least introduce the concept here.

Runmodes can be used to help Sling determine which set of configuration options should be selected from within a given content repository. In this brief example, I’m going to show you how you can change a particular OSGi config back and forth with no changes to the code base or the JCR, but rather just by changing the arguments we pass to Adobe Experience Manager when it boots. At Axis41, our Managed Services team uses these runmodes extensively to empower our automation tooling.

In order to demonstrate the feature, I will be generating a small JSP file in my repo; it doesn’t really matter where. Here’s the JSP code:

        

              The config for this pid says that "sling.max.calls" is 
              
        

This just gives us a page to read a specific OSGi Configuration; I picked one more or less at random. Normally, our components will read these values from a service, and those services will use a reference to the OSGi Configuration, so we don’t have to write all this code—I was just taking the cheap way out for a quick demonstration.

Now I’m going to create two different folders—config.publish.stage and config.prod; note that by putting multiple runmodes in the folder name, I restrict it down further. That is to say, “config.prod” would apply to any node that has the runmode “prod” (our Production lane)—whether Author or Publish—while “config.publish.stage” would only apply to Publish instances in the Stage lane.

As you can see, each of these folders has a single “sling:osgiConfig” node inside it, and the name of that node is the same as the Service PID we are trying to configure (org.apache.sling.engine.impl.SlingMainServlet). An additional property is added to the node to set the config property we want to customize based on the runmodes (sling.max.calls). When our active runmode is “prod”, we’d like it set to 1750, while we want it at 1575 in the Publish instances using the “stage” runmode.

When we start the AEM instance with the runmodes “publish,stage” and load the page we created to dump the value, we should see output that looks something like this:

Now we can stop AEM and start it with the runmode “publish,prod” and confirm that the value indeed updates to the new setting:

In a real-world scenario, there are a handful of configs that we almost ALWAYS want to set differently based on the lane (Prod, Stage, Dev, etc.); some examples include loggers, JCR Resource Resolver (used to power the “/etc/map” system; this is often used for mapping domains to content paths) mailer configs, LDAP server names, and search engine settings.

Hopefully this has introduced to you the power of Sling’s runmode, and stay tuned to aempodcast.com for a much more in-depth discussion of how these can be leveraged to manage your Adobe Experience Manager stack.

A question came into the blog a while back asking for some help about Adobe Experience Manager workflows. We recommended that the person look into our articles about workflows that we had done in the past. However, he was having some trouble (possibly because the documentation he was referring to was from CQ5.4 and Adobe documentation is sometimes a little sparse). Here is what he sent to us:

“I created a Workflow, using documentation from this URL: http://blogs.adobe.com/learningwem/2011/11/30/cq5-4-workflow-example-approve-reject-by-the-reviewer/. I created two users: auth (Author) and app (Approver) with some ACLs. I logged in as auth, created a page, authored it, and triggered the workflow to activate it. I then logged in as app and saw the task in the Inbox. I am able to complete the task and the page will be published. But when I selected ‘Step Back’ button, it displays ‘There are no items that can step back.’”

The workflow has only one step; Reviewer. But if reviewer finds faults, how do you step back? Should it not go to workflow initiator, who is the author?”

Since this may not be expressly stated anywhere, let us state it now. You can’t step back a workflow process if there is only one step in the workflow. Stepping back moves the payload from one step to the previous step—so you can’t step back if you are in the first step of a workflow process. Stepping back can’t terminate the workflow.

One solution would be to add another step before the approval step called review, which would require the author to review his work before moving the payload into the approval step. The author would trigger this workflow and then move the page into the approval step. It would be a two-step process for the author, so the approver could step back the workflow to the author.

The disadvantage to this approach is that the workflow has only one outcome, which is publication. In order for the content in question to be completely denied for publication, the author has to terminate the workflow. Documentation on terminating workflows can be found here: https://docs.adobe.com/docs/en/aem/6-1/administer/operations/workflows/wf-admin.html.

My recommendation would be to use Step Back as an exception rather than part of the standard workflow process. My reason for this is because it defeats the principle and concept of having a workflow process.

A preferred solution would be to put an OR split in the workflow that would allow the approver to choose either approve or reject. Approval would be an automated step that would automatically publish the content. The reject step could be an automated step that would simply end the workflow by doing no action, or it could be a user step that would notify the initiator (in this case the author) that the content was rejected.

The main advantage to this approach is that the workflow always has an endpoint that will complete the workflow. Having workflows remain in limbo can sometimes cause confusion if they are constantly being bounced back and forth between approval and review.

Another advantage to this approach is in the notification step that can be added in the rejection branch that notifies the author about the rejection. This step can be used to give the author feedback as to why the content was rejected and what needs to be changed. Some people have chosen to use comments in the workflow step to convey such information.

I also strongly recommend reading the AEM 5.6.1 workflow documentation since it contains more updated information, especially for this use case.

https://docs.adobe.com/docs/en/cq/5-6-1/workflows/create-models.html#Defining%20a%20Rule%20for%20an%20OR%20Split
OR
https://docs.adobe.com/docs/en/cq/5-6-1/workflows/wf-overview.html

If you are using a more updated version of AEM, then I suggest reading the most updated documentation here for AEM 6.2.

We hope this helps any of you who run into a similar problem setting up a workflow. If you have any other ideas about how to handle this, then feel free to share it with us and we will update this blog post. Send the ideas to info@aempodcast.com.

The gun enthusiast community is huge, and Browning is a big part of it. As such they were keen to be able to use AEM’s User Generated Content (UGC) system for their community. But Adobe is kind of notorious for having great solutions but not documenting how to use them (It’s tough when you have so much functionality in your offerings). One part of Adobe Experience Manager where this is the case is UGC. We sat down with Adobe Certified Expert Hisham Djobo, a developer with Axis41, who worked on Browning’s “Show Us Your Buckmark” section, which utilizes UGC. Hisham had to spend a lot of time figuring out how this poorly documented part of AEM worked to accomplish the customer’s need to continue to foster Browning’s community. In this podcast we discuss: What we mean by User Generated Content, reverse replication, the problems we faced, how we solved them, and how they dealt with spam.

The Question
A few months ago, one of our customers who self-manages their Adobe Experience Manager stack was doing some digging in the filesystem underneath the crx-quickstart folder. They noticed a correlation between the filenames found there (specifically, under crx-quickstart/launchpad/config and the changes they would make in the Felix Console at system/console/configMgr to configure OSGi bundles.) Putting two and two together, this enterprising SysAdmin asked me:
“If I pull those out and drop them into a fresh instance and restart, will that ‘configure’ [the bundle] for me? Is this the best way to accomplish this and similar tasks? Are there API calls I can make to the site to configure these types of things? I’m trying to gauge what it’s going to take to stand up a fully functional instance without having to touch it every time. It seems awfully cumbersome to track down these files after every configuration piece. Do you have any pro-tips?”

Our Answer
While it was awesome that this guy found the correlation, we were quick to reply that we do NOT consider managing these text files to be an ideal way of configuring OSGi services. The better solution, we feel, is to put these configurations into your source control such that they are created as sling:osgiConfig nodes inside your JCR. There are two solutions for that.

Setting up the Package Structure
The short answer is to create the nodes directly with your IDE under jcr_root/apps/myproject/config in one of the existing modules.

Here’s an asciinema recording of me looking at such a setup on my own filesystem. However, Systems Admins are frequently not Adobe Experience Manager Developers, so it’s a lot to expect them to know/remember the directory structure and XML syntax for these configuration files. An easier way to create these things is by making the appropriate node in a CRXDE Lite running locally, and then using VLT (or CRXDE Lite’s Package Manager) to export the node structure and send it to the developers for incorporation into the code repository.

How Many Settings Could a Sysadmin Set If a Sysadmin Could Set Settings?
When doing it via this method, I sometimes begin by going to /system/console/configMgr and finding the service I want to configure. Clicking on the service in this screen opens a dialog.

Here, by way of example, is the dialog for the Apache Jackrabbit Oak Default Sync Handler:

In the CRXDE Lite, make a new node under /apps/ /config, of type sling:osgiConfig.

The node’s name will be based on the PID found at the bottom of the configMgr dialog. If the service being configured is a factory (as Apache Jackrabbit Oak Default Sync Handler is), then we will append .config. to the”Factory PID” instead.

When Felix creates these nodes for you, it will put a UUID in the space, but this can really be any distinct value you choose—I usually like to choose a more meaningful name so I don’t have to remember UUIDs. This .config. is used because, as a Service Factory, there can be many distinct configurations of the same service living side by side; for example, we may want a different one per site.

Here’s what the dialog looks like CRXDE Lite:

For each configuration value in the dialog, we will create an appropriate property on this new sling:osgiConfig node. The name of the property will be the name in parens at the end of the documentation string:

The type of the property will depend on the value; you should always refer to the API documentation for a given service the first few times you configure it, but after a while you start to notice a few patterns between the datatypes of service properties and their representation in the OSGi Configuration Manager. For example:

• checkboxes are represented as a Boolean
• simple integer values (e.g., user.membershipNestingDepth in the above) are of type Long in the service
• pretty much everything else is a String

Also, pay attention to the little +/- buttons along the right edge of some inputs; where these appear, you should select the “Multi” toggle:

When you have “Multi” selected, hitting “Add” will open a multi-value dialog. Input the appropriate values (in this specific case, there are none to enter, so we leave the initial box blank) and hit OK.

Here’s what the completed sling:osgiConfig will look like:

Save your work and use the “vlt” command-line tool to export this. Here’s an example invocation using the default password of “admin” and connecting to an instance running on localhost:4502:
vlt –credentials admin:admin export -v -t platform http://localhost:4502/crx /apps/myproject somedir

That will create the same directory structure you saw in the asciinema above (it is, in fact, exactly how I created that structure.)

Now, your OSGi configurations can be moved into your change management process, giving better repeatable results, and moving us further down the pipeline to Infrastructure as Code. Let me know if you have any questions about any of the above!

Let me start with a brief introduction both of myself and the purpose of this series. When I started my new position as a burgeoning Systems Administrator, I was told I would be working with Adobe Experience Manager (AEM, then called CQ), a product I had never heard of. I had to use Amazon Web Services (AWS), a cloud platform I had never worked with before. To say I felt enormous pressure to grow and perform quickly would be an understatement. The vast AEM environment felt nothing short of a desert wasteland, and I was being called to navigate. On top of this, there was quite a bit of standardization and automation that needed to be hashed out.

Thankfully I wasn’t completely alone; I had a new coworker who had been stranded in this wasteland in much the same way I was. There was also a team lead who was eternally buried behind the workload that my coworker and I had come to help tackle. I first started conceptualizing this series of articles after my first year working with AEM, thinking to myself, “What are some of the things I wish I had known from the start?”

That said, the purpose behind this series of articles is as an introduction to the administrative side of AEM. I will also impart some of the information I have picked up along the way. I will be splitting the remaining articles up as follows; Author, Publish, Dispatcher. Each of these articles will cover different pieces of information regarding the AEM stack; but before we venture too far from civilization as you know it, we need to prepare for our journey by covering some basics.

You see, I realized as I started writing up information about the different environments that there is quite a bit of other introductory information on AEM in general that might be helpful to point out. For example, sometimes you may read/hear references made about the Author environment; this can get a little confusing since we typically think of our environments in terms of “production”, “pre-production”, “development”, etc. “Author” is just one specific responsibility an instance can be assigned in AEM. So we will put a pin in the environments/responsibilities and come back to those later.

The Desert of AEM
The AEM landscape is nothing short of extensive. Like a desert, which is enormous in size and difficult to navigate, this robust content management system with integrations to the rest of the Adobe Marketing Cloud takes time and research to properly cross. AEM is built around a few open source projects with some proprietary code to hold it all together. We at Axis41 have found that AEM, due to its size and complexity, is many different things to different audiences. When looking at it from the SysOps point of view, we usually focus on two specific conceptual models: how it is delivered as a piece of software, and how it executes as a platform.

Let’s dive into the technology a little bit more. AEM has several layers for its Software Delivery Model, like an onion; at its core are the implementations of the OSGi (Apache Felix) and the JCR (Apache Jackrabbit). These are then connected with Apache Sling, which presents some added features—primarily a RESTful Framework, scripting engines, and an authentication layer. This is then wrapped up with Adobe’s CRX, which adds some proprietary features such as the Author/Publish model, replication support, and tools for management and development, just to name a few. The next layer is then the actual Adobe Experience Manager; this brings with it additional management tools for Campaigns, Websites, Assets, Tags, and Workflows.

Moving on we will take a high-level look at the execution model for AEM. The OS executes AEM as a Java application that will run in one of two modes, Author or Publish. Author is the main interface that content creators and developers will interact with. Publish is the “work-camel” of the AEM suite; it takes all the dynamic content and generates static data ready to be delivered to browsers. As AEM is a Java application, it also kicks off the JVM with the flags you have defined. The JVM executes Felix (OSGi), which in turn executes Jackrabbit (JCR), Sling, and the WCM.

Something I have noticed, especially with production environments, is that AEM tends to struggle if you allocate less than 2GB of memory to the JVM. Also, the JDK and Java version you use matters. For AEM versions earlier than 6.0 SP2, you will not be able to use Java 8, and OpenJDK is unsupported.

Planning Your AEM Expedition
Before undertaking your desert excursion, you ought to be certain that everything is in order, like the amount of food and water that you have and the location of various checkpoints along your way. You also need to know how AEM communicates to the other servers in the stack ahead of time. It is important to note that the information I am providing is the default and recommended settings. These settings can be changed, but you really should have a very good reason before you do so, if for nothing else to avoid confusion later on. The image below shows the various security zones and the ports AEM uses, which will need to be whitelisted.

In a standard setup, you would have your content creators accessing the Author over port 4502 from an internal zone (or possibly through an Author-facing Dispatcher). Then you would have a zone for the Publish, which would be opened on port 4503 to communication from the Author and Dispatcher. Lastly, you would have a zone for the Dispatcher that allows communication on port 80/443 from the Author, Publish, and either the outside world or in a high-availability case from the Load Balancer.

Some additional information that you may want to be aware of is that the Publish server has a passive role—meaning it does not request information from either the Author or the Dispatcher. The Author will either push changes to or pull updates from the Publish. The Dispatcher either requests data from or sends data to the Publish. The only outside communication the Publish initiates is a simple request letting the Dispatcher know its cached content is out of date. So the Publish is really just a go between pulling double duty; first as rendering host, and secondly as a content buffer allowing content creators to make changes without them being viewed by the general public.

The AEM Caravan
Now that your travels have been mapped out, it’s important to know what your days will look like. Similarly, it’s imperative to understand how normal AEM operations work from day to day. Although this next part might sound like it’s straight from Abbott and Costello’s “Who’s on First” skit, it will give a good overview to use as a reference later on.

A content author signs into the Author instance and makes updates to a site page. This is then activated and can trigger a workflow for the content to be reviewed by another party. Once the new content is approved, it is pushed out to the Publish instances in the stack. These Publish instances, after ingesting the changes, then send an invalidation request to the Dispatchers letting them know the page has been updated. Lastly, an end user sends a request through the Load Balancer to view the page that has been changed. The Dispatcher recognizes that the requested page was invalidated and checks for a new version from the Publish. The Dispatcher caches the updated page and serves the request back to the end user. The image below may help visualize this process.

With this information out of the way, you should be somewhat versed in the basics, which will help with further discussions of AEM. Whereas none of this is extremely complex, this information will better prepare you for the journey we will be taking together. You’re now armed and ready with what you need to begin the AEM journey as we venture into the great expanse and take a look at the various roles that exist within AEM. Our first stop is the Author.

If you have questions or comments feel free to email info@aempodcast.com.

During Adobe Summit 2016, we had a chance to talk with Gabriel Walt, Product Manager of Web Experience Management, about the new functionality of the Template Editor for Adobe Experience Manager 6.2. I was also able to attend the breakout session/lab where he showed how it worked. It was much improved from what I had seen a year earlier. Still, there are some concerns that you should consider when setting this up for your authors, most notably the permissions for who can actually do it. In this podcast we are joined by Adobe Certified Expert in Adobe Experience Manager, Ken Woodward, where we will discuss his thoughts about the template editor in AEM 6.2 as well as play some audio that we recorded with Gabriel Walt at Adobe Summit 2016.

Here are some of links that we mentioned in the recording that you might find helpful as you get started using the Template Editor:

• AEM 6.2 Template Editor Workbook https://s3.amazonaws.com/qnuyfhrc/L314-summit-template-editor-workbook.pdf
• Adobe Experience Manager 6.2 Template developer docs https://docs.adobe.com/docs/en/aem/6-2/develop/templates.html
• Adobe Experience Manager 6.2 Editable Templates developer doc https://docs.adobe.com/docs/en/aem/6-2/develop/templates/page-templates-editable.html
• Adobe Experience Manager 6.2 Creating Templates developer doc https://docs.adobe.com/docs/en/aem/6-2/author/site-page-features/templates.html
• Known issues of 6.2 https://docs.adobe.com/docs/en/aem/6-2/release-notes/known-issues.html
• 6.2 Release Notes https://docs.adobe.com/docs/en/aem/6-2/release-notes.html

[EDIT: Here is a link to the AEM 6.2 Template Editor Workbook that Ken referenced in the podcast. Gabriel was nice enough to share it.]

Share your experiences/opinions with the Template Editor for Adobe Experience Manager 6.2 on Twitter @axis41.

Having prepared for the journey, you’re now ready to venture into the desert of Adobe Experience Manager and learn about the mystical Author. Ok, I am not sure I would really call the AEM Author mystical, but it sure can bewilder the uninitiated. For those of you who are returning for the second installment of this series of articles, I mentioned we would be digging into the various responsibilities within AEM. We’re going to discuss the Author instance, from its purpose through setup and maintenance. The setup and configuration for Author can also be found in Adobe’s documentation. The same process can be followed more or less for the Publish instance, which we will talk about in our next article. For those of you who haven’t read my first article, it covers some high-level information on AEM. Unless you are already familiar with the basic concepts surrounding AEM, I would suggest giving it a quick read before moving on.

Another quick note is that throughout the article I will reference ACS AEM Commons, which is a package provided by Adobe Consulting Services. Essentially, they generalize and make available tools they have created and package them as an add-on to AEM. These features can be extremely helpful and potentially save you and your developers a lot of time and frustration. I recommend including this package on all of your AEM installations. Let’s get started.

The AEM Caravan Lead
As you embark on your journey, it’s important to look to the leader to guide the expedition. Similarly within Adobe Experience Manager, it’s important to look to the Author to guide the creation and management of content. This server should be thought of as the lead instance in AEM. Developers will create templates and components for the the content creators to use on Author; content creators will create pages and import digital assets here as well. As a systems guy or gal, this is where all the configs are stored. The idea here is that everything, even configs that apply only to a Publish instance, is stored on Author and then replicated to Publish servers. Run modes, Author or Publish, for example, are then used to tell the servers if configs should be loaded or not. So really, in a worst case scenario, as long as you have a good backup of your Author instance, you will be able to restore your AEM stack. This does mean that inherently AEM has a single point of failure, the Author. I would suggest becoming very serious about your backup processes, if you are not already—especially when it comes to the Author.

As I mentioned above, Author is where content is created; when you first start an Author instance it installs code that is Author specific, basically the editing dialogs and tools. Just in case any of you were thinking “Well, I’ll just set up one Author and then save time by copying that instance and use it as a Publish”—don’t do it. I know you were thinking it, but don’t do it. You will end up having two Authors and you will run into all kinds of “fun”. This is because of installation run modes, and we’ll talk about those in a minute.

Currently Adobe Experience Manager is in a period of transition when it comes to the web interface; they are working toward Touch UI. What this means is the classic, older tools are being replaced gradually. So tools you might have used the past, including those that are mentioned in this article and others, might change slightly or entirely. With that in mind, I am going to share some paths that as an admin will be helpful to remember. I am going to list them with a quick description and include the alternate paths if there are old and new versions.

• High-level navigation of the content tree; manage, activate, or deactivate pages
  • /siteadmin (classic tool)
  • /sites.html
• Allows you to create users and groups, and manage permissions and members
  • /useradmin (classic tool: permissions can be managed here or under “Access Control” in the CRXDE)
  • /libs/granite/security/content/useradmin.html and
  • /libs/granite/security/content/groupadmin.html
• High-level navigation of digital assets
  • /damadmin (classic tool)
  • /assets.html
• High-level navigation for AEM tools, including ACS Commons
  • /miscadmin
• Disk space reports
  • /etc/reports/diskusage.html
• Replication agents and tree activation
  • /etc/replication.html
• Workflow manager
  • /libs/cq/workflow/content/console.html
• OSGI console access
  • /system/console/bundles – Default page, list of bundles
  • /system/console/configMgr – List of service configurations
  • /system/console/slinglog – Quick access to logging information and configs
  • /system/console/jcrresolver – Useful for testing sling mapping configurations
• Tree-like navigation of the nodes in the JCR
  • /crx/de/index.jsp (CRXDE)

Gaining AEM Ground
As you make your way across the desert, you want to be sure that you’re doing everything possible to maximize your time. You also want to do that with regard to your AEM installation to ensure you’re getting the most out of your investment. When you read through documentation on getting started with AEM, you have the option of double-clicking a JAR file, which will start a local instance of AEM that you can play with; this is great for local testing but not so helpful for a headless server environment. As a rule of thumb when I want to work with Adobe Experience Manager, I have gotten into the habit of doing an unpack on the JAR file (java -jar /path/to/file/aem.jar -unpack), which will extract everything into a directory named “crx-quickstart”. This is an important directory; it is pretty much where all of AEM will live—think of it as AEM’s home directory. This directory can be copied or moved and it will contain your entire AEM installation.

Starting or stopping AEM after an unpack is fairly simple as there are scripts located in the crx-quickstart/bin directory. You can either run these directly, or the better option would be to create a daemon service script that exports the values needed to start AEM, such as the JVM Options and run modes.

I have mentioned run modes a few times, so let me take a quick moment to talk about them here as there are really two types.

Installation run modes are applied the first time you run AEM and then fixed for the entire lifetime of the instance; they cannot be changed later on down the road.

• Persistence Manager – Determine how data persists, i.e., crx2, crx3, crx3mongo
• Role – Determines what responsibilities are assigned to AEM, i.e., Author or Publish
• Samplecontent – installs Adobe’s sample Geometrixx content

Note: By default, samplecontent is added to the installation run modes. If you specify “nosamplecontent”, you will instead get a version of AEM that matches Adobe’s Production-Ready Checklist. What is obvious about this is that sample content and users are not installed, but it also causes some bundles from being installed that you cannot easily get back. For actual production environments this can be helpful, but in the non-production stacks it might make things a little difficult. For non-production environments, you may want to consider allowing sample content to be installed and then remove the Geometrixx packages after.

Customized run modes are applied on each startup and can be changed with a restart of AEM. They allow you to define run modes that can be used to identify the instance that’s running and modify its configurations accordingly. An example would be to set a “production” run mode, so you can identify configs that should only be applied to a production instance.

Conserving Water
In the desert, you have to know how to manage your water supply. The same holds true for “flushing” cached content in AEM. Now, I mentioned in the first article how information that is created on the Author is passed through the stack to reach the end user. This process can run through several workflows, but at the end of the day it is still all handled by replication events. I also mentioned a little earlier in this article that you want to ideally keep everything on Author and then replicate (push) that out to Publish instances. This holds true for the Dispatcher agents as well. You should be in the habit of configuring those nodes on the Author, even though they live under the agents.publish directory, and then push them to your pubs. Now, you might ask, “Why not just have the Author flush the cached content from the Dispatchers?” Well I am glad you asked—you see the issue with having the Author flush content that has just been activated is that sometimes it takes the Publish instances a moment to ingest that content. This is especially true if there are a lot of replication events happening. This then creates an issue where the Dispatcher is trying to re-cache that page but the Publish isn’t ready to render it, so you end up caching broken pages. Thus, you should have your Publish instances flush your Dispatchers in all cases but one.

What is that one case you ask? Another great question. There is a tool packaged with ACS commons called the “Dispatcher Flush UI”, which allows you to create pages that content creators can use to flush pages manually from the Dispatcher. This is safe to do from the Author, but you will need to make sure you enable a flush agent for each Dispatcher on your Author, and that you have the “Ignore default” option selected. This allows ACS Commons to send a flush request from the Author while normal activations will continue to use flush agents on Publish.

Scheduled Breaks
During your journey, you need to ensure that you’ve scheduled time for breaks. You also might want to schedule something of similar importance within AEM. I mentioned the importance of taking backups a little earlier, and if you’re wondering how you can trigger these on a schedule, then you are in luck. We can cover this in more detail later, but for those of you who are looking for a solution right now, when AEM triggers a backup it sends a ReSTful request to start the process. Knowing this can help get you started.

Speaking of ReSTful, calls I should also mention there are quite a few articles out there that cover different cURL commands that can be used with AEM, as such I will not cover those commands in this article. I will however mention something that may prove useful: Adobe Experience Manager is built on a ReSTful framework, which means anything you can do through a console or the CRXDE you can make a ReST call to perform the same action. Although finding exactly the calls that are being made can sometimes be difficult, more often than not they are pretty simple to determine using this method I have picked up along the way. Chrome’s debug tool has this nifty option to copy any request from the network tab as a cURL. This means you can click the Preserve Log box, go into a local AEM instance, make your request using the CRXDE, and then see the result of that request in Chrome. You can then select that request and copy as cURL. Viola! You can now make the same request through the command line, shell script, or what have you.

We have now covered a bit of the basics talking about the Author environment, and getting the Author server started up. Although we could dig even deeper into the Author, this should help you to better understand how Author fits into the AEM stack. That’s two articles down and more to come—make sure to subscribe to the blog to stay tuned. We will be covering the Publish environment next as we continue to traverse the AEM landscape.

A great opportunity is being offered for those interested in becoming an Adobe Certified Expert as an Adobe Experience Manager Developer on July 19. The Adobe Communities team is offering a free session to help prepare people for the Adobe Experience Manager Developer Exam. Here is a link to check out the details for this session. This is being presented by Adobe experts Scott Macdonald (who manages and posts on http://scottsdigitalcommunity.blogspot.com/) and James Talbot (who has worked for 16 years as a solution consultant, sales engineer, trainer, evangelist, and is currently managing a team of AEM subject matter experts). This is a chance to listen to the experts. Even if you can’t join, I believe that they make the recording available afterward for those that wish to watch it later. This is a great opportunity for anyone looking to better themselves by gaining a certification.

Did I mention it is free? Go sign up!

You’re tired, thirsty and maybe a little cranky. I get it; Adobe Experience Manager can be a little frustrating and overwhelming. It might make you feel like you have been left in a desolate wasteland with nothing but your wits and a half empty—or half full—canteen. Never fear. With these articles you will have another tool in your belt to make it across the desert. Today we will cover the Publish server in AEM; and as mentioned in my introductory article, the Publish server is the workhorse of AEM. What do you mean you haven’t read my first two articles? The first article covers some basics about Adobe Experience Manager. The second article covers the Author server and its role within the AEM stack. I do sometimes reference back to those articles and It could be helpful to read them before moving on, but I won’t make you.

Just like the Author, the Publish also runs as a Java application; in fact, most of the information about setup and startup from the Author applies to the Publish as well (they even use the same jar). This means that the steps to get a Publish server up and running are going to feel like déjà vu. You will obviously want to use the installation run mode of publish, and the default port changes as well (Author :4502, Publish :4503). Other than those changes, you are looking at the same process. Let’s move on and learn more about the Publish instance.

The Desert Oasis – A Return to Familiar Ground
The Publish server is your return to an oasis during your journey as you’re well equipped for the task, having already set up the Author. The Publish server in the AEM stack is a render host and is the first way it differs from the Author instance. The Author pushes new content to the Publish server and it ingests that content. The Dispatcher sends requests to the Publish to be rendered and returned so it can cache and deliver them. The point I want to get across here is that the Publish is not starting these communications; instead it’s processing requests as they come in from the rest of the stack. Now, just because the Publish is zen regarding communication doesn’t mean it isn’t doing anything. In fact, most of the time the Publish will be the busiest of the two Java applications. It has to render all that code and process the logic you or the developers created and turn it into static content; i.e., HTML, CSS, JavaScript, etc. It also handles other tasks such as queries coming through the Dispatcher. The Publish is also where requests to flush the Dispatcher originate. These requests to the Dispatcher are normally only triggered after content has been ingested.

The second difference is that the Publish does not have the Authoring UI. As such, making changes directly to the Publish server should not be done. Normally I am not going to tell you how to manage your stack; instead I will give examples and suggestions. For this I am just going to be blunt and tell you—do not create anything directly on the Publish server. The Publish server has its purposes in the stack; manual configuration and changes is not one of them. Instead, changes or config settings should be created on Author and then replicated to Publish. Remembering this will help you avoid situations where content or configs are mysteriously overwritten. I am going to cover a little bit about configs and touch briefly on those run modes again a little later on.

Scaling for Your Journey’s Load
Having regrouped at the oasis, it’s time to determine if you will need to bring on other resources to help with the load. As the Publish server normally deals with a larger load than the Author, it’s nice that it’s also easier to scale than the Author. In the Introduction article there was a graphic that showed the standard Adobe Experience Manager architecture we employ here at Axis41. If you refer back to that image, you will see that we have two Publish servers, which could just as easily be changed to three, four, or more depending on the load and needs of your project. As long as you remember to create a Publish agent on your Author, you can keep more than one Publish up to date and ready to ingest and serve content. Besides scaling for load, the other reason we recommend running with two or more Publish/Dispatcher servers is for higher availability. This allows you to load balance across different geographic locations. It also allows you to perform maintenance on one of the Publish/Dispatcher lines without reducing availability for end users. This same technique could also be used to have a disaster recovery option available as a hot standby.

Note: Scaling Publish servers, or creating a hot standby, may include additional costs for licensing and you should check with your Sales Rep to make sure you are in compliance.

The Refetching Mirage
In my Author article, I talked a little bit about letting the Publish handle flush requests. There are really two types of flush agents available to you on the Publish—the flush and re-fetch agents. In simple terms, the flush agent sends a request to the Dispatcher to invalidate its cache, so on the next request the Dispatcher will get a new render from the Publish. The re-fetch agent sends a POST request to the Dispatcher that will delete the cache and then trigger an immediate re-cache event so that there is no extra wait time when that resource is next requested. The re-fetch agents sounds pretty great, however there is a cost associated with this agent. The major issue here is that the request made by the Dispatcher isn’t the same as a request made from a browser; this can cause irregularities when a page is cached. The re-fetch also triggers an immediate re-cache; if there are many resources being flushed, this can put a large amount of load on the Publish, creating a snowball effect and making the Publish slow down for all tasks.

The other agent you may see or want to use on Publish is the reverse replication agent. Remembering that the Publish is a render host, also means that it will not try to push content to Author, nor should it. This would appear to cause issues with user-generated content such as comments, reviews, etc., getting back to Author or the other Publish servers. AEM, therefore, has the option to enable reverse replication. The Publish stores user-generated content in a special outbox. The Author periodically requests from the Publish anything in the reverse replication outbox, and pulls that content in. The Author can then pass this content through an approval workflow, if needed, and replicate the user-generated content to the other Publish instances.

Publish Configs along Your Route
Now that we’ve talked about scaling your load and visited the refetching mirage, it’s time to cover what the last leg of your Publish journey will entail: configurations. We’ll begin by discussing configurations that normally you’ll only want configured on the Publish instance, or maybe you want them working differently on Publish. First, the way to make these configs only apply to Publish is by accessing those run modes we talked about in the Author article. Remember there are installation run modes, two of which are Author and Publish. This means you can use these run modes to identify which servers to apply the configs to. Adobe Experience Manager has a feature where if you place a directory named config. under the app/project directory, it will automagically apply any configs in that directory only if the run modes match. Armed with this knowledge, you can take it one step further and use multiple run modes, such as config.publish.production, which will only apply to a Publish server also using the production run mode.

So if you have settings that only apply to production, such as mail server settings for contact forms, then you can make sure that only applies in the right situations. Creating these config nodes can be a little bit of a challenge, but luckily for you there is a post right here on AEM Podcast that covers this process.

“Etc” Map Rules to Your Destination
The final configurations that you normally apply only to Publish are etc map rules, so named because of the default path by which they are found in AEM: /etc/map. Think of them as markers along your desert map.

These configurations are officially called Resource Resolver Mapping, and they allow you to rewrite hrefs on pages to strip out paths that you may not want exposed to an end user. A classic example is removing /content/sitename/en from links for SEO as well as security purposes. I am not really going to cover all the specifics of setting up etc map rules; instead, I will cover how to make etc map rules only apply in the same way that other configs do—by leveraging a sling OSGI configuration node inside of a run mode named config directory.

You will need to have a config node named “org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.sitename” created under config.publish.

Next you will need to add or modify a property on that JcrResourceResolver config, resource.resolver.map.location. Set it as a string, and then for the value enter a unique etc map path; I would suggest something like /etc/map.publish so as not to confuse it with anything else. What this does is tell the Resource Resolver that it should load its rules from the directory you defined.

You can then set up your etc map rules under that same directory and they will only apply to Publish servers. You can also take this one step further and create the JcrResourceResolver config under config.publish.production and create a map location of /etc/map.publish.production and have rules that apply only to a server that is both Publish and production.

Like the Author article, we really only covered the basics of the Publish server and its configurations. I hope this has shed some light into how the Publish server works and some of the customizations you may need or want to set up. Our next, and final, article will cover the DIspatcher; which for some may be the most frustrating of the servers to set up and configure. Make sure you subscribe and come back as we finish our journey through the desert of AEM, and finally make it out.

With the new, juicy features of the recent AEM releases, you might be finding yourself needing to upgrade your environment version of Adobe Experience Manager from 5.x to 6.x. Along with that upgrade, you’ll now have Touch UI component dialog features at your fingertips. That’s great for all the new components you’ll be developing, but what about all the components you already developed in the Classic UI? Not to worry; since early 2015, Adobe has been providing a conversion tool that helps with shaping up your classic components to use the new Touch UI features. In this article, I will go through where to get the conversion tool, how to install it, how to use it, and a few caveats when you are using it.

Acquiring the Tool
First, let’s import the Dialog Conversion tool into your project. Adobe distributes this package through their Package Share system found here. You’ll need a valid Adobe ID to be able to log in (don’t worry, anyone can sign up for an Adobe ID). Once logged in, you can search for the package we need: cq-dialog-conversion-content. When you find it, you should see something like this:

Switch to the “ASSETS” tab and download the package to disk.

Now that you’ve acquired the package, let’s upload it and then install it to your environment. Go to your package manager, upload the package, and then install it.

Now let’s go to the tool. Navigate there by going to Tools->Operations->Dialog Conversion. Alternatively, use this direct url to access the tool.

How to Use It
Now that you have the dialog conversion tool, let’s talk about how to use the tool. First you need to enter a path that contains your components (or browse to it using the path browser button), and then click the “Show dialogs” button.

Next, you’ll be presented with the list of dialogs contained within the path you specified. Mark the checkboxes of the dialogs that you want to convert and click the “Convert # dialogs” button.

From there, you’ll need to get the code that it generated and put it into your code repository. You can use the “crxde” link next to each dialog you converted to view where the new dialog has been created in your instance (the Touch UI dialog will be in the cq:dialog node, inside the same level as your Classic dialog).

You’ll need to use the package manager and create a new package with a filter for that cq:dialog.

Build the new package you made and download it. When you unzip the download, drill into the directories until you get to the directory named _cq_dialog. This directory will contain the .content.xml file that you want.

This .content.xml file contains all the XML that Adobe Experience Manager uses to build the dialog nodes. It looks very similar to the dialog.xml file that generates your Classic dialog, with a few noticeable differences: all the jcr:primaryType properties will have the value of “nt:unstructured”, and it uses sling:resourceTypes instead of xTypes.

Classic UI Dialog Format:

Touch UI Dialog Format:

To add this to your code, simply create a _cq_dialog in the component directory, and add your .content.xml file inside of that.

Caveats
Out of the box, this dialog tool does a phenomenal job with most basic dialogs, but it struggles with certain nuances. You’ll notice in your converted dialogs that some xTypes don’t translate well. Some examples are datefield, the Rich Text Editor, or any custom xTypes you’ve made. For these, you’ll need to pick a sling:resourceType that will work for you, or create a custom sling:resource. Also, it’s worth mentioning that there are ways to customize this tool by defining your own rewrite rules to be able to handle the automatic conversion of these trickier paradigms.

Conclusion
That’s all the basics of the Dialog Conversion Tool. You know where to get it, how to install it, how to use it, and the gotchas to watch out for. The Dialog Conversion Tool is a must-have for when you decide to upgrade to Touch UI. Using this tool helped my team and I successfully upgrade from 5.61 to 6.1 quickly with minimal hold-ups. For more information on the tool, view the documentation here.

You know how sometimes, you get close to the end of your journey and it makes it feel like something short is something long. This will not be one of those cases as the last leg of this journey talks about the Dispatcher, and there is a lot to cover in a short space. For those of you who may have stumbled upon this article without reading the others in this series let me first say welcome. You are joining us at the tail end of our journey; a four part series about the Adobe Experience Manager infrastructure. To recap what you may have missed. The first article covers some AEM terms and basics, the second article covers the Author server, and the third article covers the Publish server. If you have no prior AEM knowledge it may be worthwhile to give those a look. It’s ok we will be right here when you get back. Civilization is near my friends. So sit down, strap in, and hold on, we’re taking our final ride.

What is the Dispatcher?
To start, the Dispatcher unlike the Author and Publish server is not a Java application. It is actually an httpd module, and it’s proprietary. The Dispatcher pulls double duty in the AEM stack, it serves as both a caching server, as well as something similar to a Web Application Firewall (WAF). When it comes down to it the Dispatcher is similar to other Apache run web servers, you can use Apache mods to change how traffic is handled and how the static content is served. The part that is special is the Dispatcher handler which eventually is passed the request and then it goes to work. The Dispatcher first checks the cache root, which should be the same as the DocumentRoot (more on this later). If the file being requested is not cached or has been marked as invalid, then the Dispatcher will connect to a Publish instance and pass along the request to be rendered. Once this is done the Dispatcher takes the rendered asset, saves it to the cache root, and then serves this content to the end user.

The high level of how the Dispatcher works is fairly simple to understand, however once you start digging into the configuration and customization of the Dispatcher it may seem a little overwhelming. Adobe has quite a bit of documentation on the Dispatcher, such as explanations and examples of the Dispatcher’s configuration. If you are unsure what something does, this documentation may shed some light on it. I am dropping this disclaimer here so I don’t have to state it multiple times below, the configurations I show you are how we at Axis41 do things, your situation or needs may vary. With that said hopefully this will get you on the right path to success. Like the other articles we are going to cover a base level configuration as well as some added tips.

Dispatcher Install
As the Dispatcher is a module there is some installation that is required, as a general rule you should try and use the latest version of the Dispatcher. The Dispatcher comes packaged as a archive and can be found for download here. As we use a linux derivative of RHEL I am going to use that as my example, obviously some of the same information will apply even if you are running a different platform. The way the Dispatcher is packaged you can drop the tar.gz file into the http directory and extract it from that location. This will add Dispatcher specific files to your conf directory and a few files at the httpd directory level. You can then move the dispatcher.so into the modules directory. For ease of use I would then recommend creating a symlink between the versioned .so and mod_dispatcher.so. Once this is done you can then look at the files in the conf directory. One of those files httpd.conf.disp2 is an example httpd.conf file that contains the Dispatcher IfModule configuration.

You have a few options here, the first option is my strong recommendation, as it can save you a lot of frustration later on. I will also mention a couple other ways this could be handled, but seriously just chose number one.

1. Create a custom conf file with just the Dispatcher LoadModule and IfModule inside and then have Apache include your custom conf file. This is fairly easy to do, and has the added benefit that you don’t need to go mucking about in your httpd.conf file.
2. Copy out the LoadModule and IfModule lines from the above mentioned httpd.conf.disp2 example file and move those lines into your existing httpd.conf file.
3. Replace your existing httpd.conf with the example file. If you have a vanilla Apache installation is the only time I would even consider this, and even then I would still chose option one.

Once you have decided how you are going to implement the Dispatcher configurations you can start customizing. To start you off I would highly recommend setting DisspatcherUseProcessedURL to “On”, this allows you to modify the request such as with mod_rewrite and then have the Dispatcher use the updated request.

Dispatcher.any
If you thought installing the Dispatcher and setting up the IfModule configuration was all that is needed, then I have a surprise for you. There is another more comprehensive configuration file called dispatcher.any, and no “any” is not a typo. This file is mainly responsible for how the Dispatcher will behave. Inside this file there are sections that are each responsible for a different part of this behavior. Again in the interest of time I am using the default dispatcher.any file which is covered in Adobe’s documentation. What I am going to cover is some of the changes you might want to make as well as some of the configurations to pay specific attention to. The /website section is normally where you will start to configure things, you can even setup multiple websites each using the /virtualhosts section contained within to tie specific domains to specific Dispatcher configurations, just be aware that once you start down that road things can become tricky very quickly. We are going to stick with using one website using a wildcard for all domains. The /clientheaders section by default uses a wildcard and I would recommend specifying the headers you expect the Dispatcher to see.

/renders
This section sets up your Publish backend that the Dispatcher will connect to. The Dispatcher does have the ability to set up connections to more than one Publish backend, which will allow the Dispatcher to load balance between the Publish servers. If you are only using one Dispatcher this may be the way to go, however if you use two Dispatchers and two Publish servers I would not recommend setting connections to both Publish servers and here is why. In theory having the cross talking between two Publish and two Dispatchers seems like it would be a good thing. In practice you can run into an issue where the Publish server tells the Dispatcher to invalidate a page, then that Dispatcher, because of load balancing, requests the page from another Publish server which has not yet finished ingesting the content from Author. This then results in either out of date content, or content that is cached with errors on page. In essence you can end up with bad cache on one Dispatcher, and then to further complicate the matter because of load balancing it can be difficult to diagnose which Publish served up the bad content. This is why we recommend using a one to one Publish to Dispatcher configuration.

/filter
This section is where the WAF behavior comes into play. It is fairly straightforward if you look at the rules in the default file. The concept is to deny everything first and then whitelist only the requests that make sense for your project. This section is also setup so that the last rule wins. This means if you place broad rules near the bottom, those rules may expose or open up paths that you previously meant to restrict. These filters can be expanded to address each part of the http request; allowing you to move away from glob and wildcards to a more secure multi filter rule. For example using { /type “allow” /method “GET” /url “/content*” } tightens security when whitelisting the content path by only allowing GET requests to those paths. You can also do a similar filter to only allow POST to a specific servlet { /type “allow” /method “GET” /url “/bin/customservlet” }. If you are using a version earlier than 4.1.9 these expanded filters are not available and I would strongly recommend upgrading to a more recent version of the dispatcher.

Caching
The /cache section and caching on the Dispatcher in general really deserve to be singled out as they are one of the major functions of the dispatcher. Let’s start by talking about caching in general and then we will talk about the /cache section of the dispatcher.any file. First it’s important to point out that anything that is not cached or not able to be cached is sent back to the Publish server each time it is requested. As a general rule you want the Dispatcher to cache as much as possible (markup as well as content). This not only removes excess load from the Publish servers, it also greatly speeds up the delivery of content to the end user. The Dispatcher by default will try and cache everything with a few important exceptions.

1. Missing extensions – If the requested path is missing an extension such as .html
2. Method Type – If the method is not a GET request
3. Errors – If the http response from the Publish server contains an error code, it will not be cached
4. Http Header – If the response.setHeader (“Dispatcher”, “no-cache”); is used
5. Authorized Headers – If the request contains authorized headers
6. Query strings – If the request contains a query string
7. Rules – If the request does not match any /rules defined under the /cache section of the dispatcher.any file

With the above list a few of these can be modified based on settings within the /cache section, which I will cover now. I also cover a couple other important properties to pay attention to in this section.

/allowAuthorized
This property allows the Dispatcher to cache content even if there is authorization being used in the headers, most of the time you would not want this behavior as you would not want content that requires authentication to be served to someone who is not authorized. If you do intend on using authorized headers but you still would like the benefits of cached content there is the option of using /auth_checker which may not be a configuration that was included with the default file.

/ignoreUrlParams
This property can allow you to cache query strings. It basically allows the Dispatcher to treat the query string as though it were a unique path to be cached. Even though this option is available to you, I would recommend trying to avoid query strings as much as possible, and instead use a selector such as page.string.html this still allows you to modify what is cached when a different string is provided as a selector. If you end up just using a query string for something like analytics tracking, which is fairly common, you can instead use something like mod_rewrite to leave the query in the URL but drop the query with a pass through to the Dispatcher.

/rules section
By default this section is set to cache everything with a wildcard, if for some reason there is a specific resource you do not want to allow to be cached you can create a rule under this section that denies that behavior.

/docroot
This property sets where the dispatcher will cache its assets on disk. This should end up being set to the same path as the Apache DocumentRoot. This sets Apache to treat the cache created by the Dispatcher as normal static assets of a website.

/statfileslevel
This property sets how deep in the directory structure the .stat files should be created, 0 being the /docroot cache path

/serveStaleOnError
This allows the Dispatcher to serve files from its cache even if they have been invalidated in the event that the Dispatcher is not able to reach the Publish backend.

Flushing
If you remember from the other articles we have talked a little bit about flushing and the different types of flushing. As the following configurations go hand in hand, I have decided to include them in this section. We will start out by talking about the easier concept which is /allowedClients this configuration is near the end of the Dispatcher.any file and it controls who, or what hosts/IPs, are allow to send flush requests to the Dispatcher. By default this section comes commented out which if left unchanged would allow anyone to send a flush request and clear your Dispatcher’s cache, which could be used as part of a denial of service attack. I strongly recommend you set this section to deny all and then only allow the hosts or IPs you trust, such as the Publish and Author servers.

Now we are going to talk about .stat files. In my opinion this method of cache invalidation is not very efficient, and it can be a little difficult to wrap your head around. So I will try to keep it as simple as I can. First off I mentioned the /statfileslevel just above, which determines how deep the .stat files are created. The .stat file itself is a zero byte file that the Dispatcher uses to help it determine if cached files are invalid. To do this when a file is requested the Dispatcher checks the last modified date of the .stat file as well as the cached file; if the .stat file is newer than the cached file the Dispatcher knows the cached file is stale. The Dispatcher will then check the /invalidate section, and anything stale that also matches a pattern in that section is then considered invalid by the Dispatcher, and requested again from the Publish. I will use an example to help explain what I mean.

Let’s say you have a site under the path /content/mysite/en and a content author updates the contact.html page located at /content/mysite/en/about-us/contact.html. When that page is activated the Dispatcher receives an invalidation for that same path located in the docroot, this file is then automatically considered invalid. Next for every level the Dispatcher traverses to reach the contact.html page it would touch a .stat file up to the number you define under /statfileslevel. So if you have that property set to 4, remembering that 0 is the root, then it would touch the following .stat files:
/.stat
/content/.stat
/content/mysite/.stat
/content/mysite/en/.stat
/content/mysite/en/about-us/.stat

Looking at the default /invalidate section rules we see { /glob “*.html” /type “allow” }. This means any .html file is allowed to be flushed, so any .html file located in the same directory where a .stat file was touched is now considered invalid by the Dispatcher. In our example you can see this would be the .html pages under /content/mysite/en/ that are mainly affected. Now if this only affected those files that would be one thing, however there are more files which will also be considered invalid. If the Dispatcher doesn’t have a .stat file at the same level as the page that was requested, it will traverse up the directory structure to find the nearest .stat file.

So, keeping with the example above if the next request was for /content/mysite/en/about-us/investors/how-to-invest.html the Dispatcher would see there is no .stat file under /content/mysite/en/about-us/investors/, as that would be at level 5. So it would then look for the nearest .stat file available, which in our case is (/content/mysite/en/about-us/.stat), and use that as its .stat file when determining if it should serve how-to-invest.html directly from cache or request it from the Publish again before serving. In our example this would mean the Dispatcher now also considers how-to-invest.html invalid. This would be the same for any other document that lives in cache under the /content/mysite/en/about directory. No matter how deep they are, they will always refer back to /content/mysite/en/about-us/.stat to see if they are invalid or not.

I should also mention the flip side, if you had a page /content/mysite/en/blog/post1.html, for example, this would not be invalid as its nearest stat file would be /content/mysite/en/blog/.stat which was not touched by updating /content/mysite/en/about-us/contact.html. You should put serious thought into your configuration when it comes to cache invalidation. Depending on your site structure, /statfileslevel, and /invalidate rules you could end up wiping out large sections of your cache by accident with a simple page update.

Apache Config
When it comes to the Apache configuration, I am not really going to cover much in the way of Apache itself. Suffice it to say that this is an Apache server that runs a custom Dispatcher handler for serving content. Like I mentioned above this means that most of the configurations you might be used to with Apache will still apply. What I am going to cover here is some configurations you can use to make the Dispatcher work a little more smoothly.

First off we use a vhost configuration block and override the Apache DocumentRoot property as well as set the Apache handler to allow the dispatcher module to take over for serving content.

DocumentRoot /opt/aem/dispatcher/docroot
SetHandler dispatcher-handler

When we covered the Publish server we talked about setting up etc/map rules, now we will talk about the Dispatcher side of that coin. For this we would be using mod_rewrite on the Dispatcher in combination with etc map rules to strip the /content/mysite/en path from URLs. To do this you could use something like I have listed below, added to that same vhost configuration I talked about above. This will add the content path back onto the request behind the scenes before the Dispatcher processes the request.

RewriteRule    ^/$                               /content/mysite/en.html      [PT,L]
RewriteRule    ^/index.html$               /                                          [R=301,L]

RewriteCond   %{REQUEST_URI}    !^/content
RewriteCond   %{REQUEST_URI}    !^/etc
RewriteCond   %{REQUEST_URI}    !^/bin
RewriteCond   %{REQUEST_URI}    !^/lib
RewriteCond   %{REQUEST_URI}    !^/apps
RewriteCond   %{REQUEST_URI}    !^/mysite
RewriteCond   %{REQUEST_URI}    !^/en
RewriteCond   %{REQUEST_URI}    !^/dam
RewriteCond   %{REQUEST_URI}    !^/assets
RewriteRule    ^/(.+)$                         /content/mysite/en/$1         [PT,L]

The other mod_rewrite you can do in the vhost file, that might make your life easier, is mapping your DAM paths. The above covers content paths, but anything under the DAM might have a path like /content/dam/mysite/. My suggestion is to setup etc/mapping to have this path changed to something like /assets/. Oh, so you noticed that I excluded /assets in my block above. Well that was intended, as now you can setup a rewrite rule to handle DAM assets.

RewriteRule    ^/assets/(.+)$                         /content/dam/mysite/$1         [PT,L]

In the immortal words of Porky Pig, “Th-th-th-that’s all folks!”. I know that this all can seem like an insurmountable task when you first start out, but hopefully these articles will speed you on your way. Now you have earned yourself a “I survived the desert of AEM” t-shirt, if such a thing existed. Make sure you take a look at some of the other articles available on this site, and as always if you have questions or comments feel free to email info@aempodcast.com. Thank you for taking this journey with me.

We all know what Adobe Experience Manager is. Some of you might be familiar with what Workfront is (formerly AtTask). But most of you are probably not aware that there is now a connector for Workfront and AEM to help streamline the process of management for your company’s different projects.

Workfront is a project management tool that allows your organization to control the flow of work on a given project. You can assign specific steps to certain users to ensure that all project tasks and assignments are on schedule and get notified when they are completed. If you want an explanation about the benefits of integrating Workfront with the Adobe platforms (Creative and Marketing clouds), then you can check out this blog post that Samantha Martin wrote on our sister site MarketingCloud41. But in general, the idea is to streamline the management of internal projects that use the Creative Cloud and Adobe Experience Manager.

One of our senior Adobe Experience Manager developers/architects (and Adobe Certified Expert), Adam Twede, wrote up some instructions on how to hook up AEM and Workfront. You can download them here. The current connector leverages the integration between Workfront’s document management features and AEM’s digital asset management system. The Workfront connecter is a pretty new integration for Adobe Experience Manager, so new features and upgrades are still happening. Workfront has some exciting feature enhancements planned for future releases of the connector. We will try to keep these instructions up to date with news of any additions or changes.

We have talked a lot about ACS AEM Commons on the site. We think that it is a great resource to Adobe Experience Manager developers. But since we have never talked about ACS Adobe Experience Manager Tools, we thought it was high time that we did. In this podcast Joey and I take time to discuss exactly what ACS Adobe Experience Manager Tools is and discuss in detail three specific tools: Explain Query, Query Editor, and CSV Asset Importer.

Really there is no great difference between Commons and Tools. But, as the website for ACS AEM Tools website clearly states, these are not things that you should ever use in your production environments. So please make sure that you don’t!

We did a podcast about Explain Query in which we talked about the usefulness of this tool. Here is a written breakdown of that podcast for this specific ACS Adobe Experience Manager Tool. Remember, these should only be used in your non-production lanes.

What is it?
From the ACS GitHub page about Explain Query: “Explain Query is a tool that explains how Oak is executing a query. For any given query, Oak attempts to figure out the best way to execute based on the repositories’ defined Oak indexes (under /oak:index). Depending on the query, different indexes may be chosen by Oak. Understanding how Oak is executing a query is the first step to optimizing the query.”

How it works
Perhaps the biggest change in the Adobe Experience Manager 6.x line is the transition to Jackrabbit Oak, which brings with it a whole new way of storing data. As a result of the new storage engine, you will likely find yourself occasionally revisiting how your content is indexed so that JCR queries can bring back the correct results in a reasonable amount of time.

Traditional relational databases have historically included a utility to help you determine where you need to improve or expand your indexes, but JCR users have largely been left to their own devices. Whether it’s a new migration to the 6.x line, or a new feature you’re implementing in an existing implementation, or just that performance has tanked because some part of the content tree grew in an unexpected way, you now have a tool you can use to determine the correct indexing on your content.

Example Application
Axis41 recently worked with a customer whose previous implementer had created an AEM 5.x implementation, which was driven by multiple levels of indirect queries; a given component would perform a query for some node properties, use those properties to build a string that was fed again into the query engine, which would return a set of node properties…and so on, ad nauseum. When we deployed this same code to Adobe Experience Manager 6.1, in some cases it would take several minutes per component to render—bringing the front page of the site to a total of 18-20 minutes to render. By taking the queries and running them through the Explain Query tool, we were able to define a set of indexes that brought much more reasonable response times (while we rewrote the implementation on a parallel work-stream to be more directly manageable).

[Update: Adobe Engineering has declared this to be working as intended; if you want this ordering to persist, a workaround like that provided below will need to be implemented.]

We discovered what looks like an oversight/bug in AEM 6.2 Assets collections (we have not investigated if this is a problem in earlier versions.) When you reorder the assets in a collection in the UI, the underlying order does not actually change (if you refresh the collection view the order goes back to what it was before). In other words, the ordering of a collection in AEM 6.2 the order is set at creation time, and you cannot make persistent modifications to it.

A customer’s project requirements included the ability for authors to change the order of assets in a collection, so we made a quick and dirty fix for this issue. Here is a link to download the code we created to get around the problem. It’s not our preferred solution, but it gets the job done. We have submitted a ticket to Daycare which has been escalated to the Engineering team and assigned ticket ID CQ-94530; if you are interested in this issue, you can use this ticket ID to watch Package Share and the Release Notes for an official patch from Adobe for this issue.

With the release of Adobe Experience Manager 6.0, Adobe introduced a new markup language. Most of us know it as Sightly. But technically its first name was HTL, short for HTML Template Library. (Thanks to our friend Ruben Reusser who posted about the new language back in December 2013. You can watch the videos here: https://ruben42.wordpress.com/2013/12/07/ready-for-sightly-the-new-aem-templating-language/.) They mentioned that they were planning to change it from HTL to something else. That “something else” became Sightly. Some of you may have been noticing that you aren’t seeing the term Sightly as much anymore. And that is because they have changed it back to HTL. Only this time, HTL stands for HTML Template Language. If you are interested in the timing, the change seemed to take place at the end of July 2016, based on the naming update we saw in this GitHub commit.

The important thing is that functionally there is no difference between them, so if you see something on the web that calls it Sightly and one that calls it HTL, just know that they are the same. You might want to update your references to it to come in line with the new name.

We did a podcast about Query Editor in which we talked about the usefulness of this tool. Here is a written breakdown of that podcast for this specific ACS Adobe Experience Manager Tool. Remember, these should only be used in your non-production lanes.

What is it?
From the ACS GitHub page about Query Editor: “QueryEditor is a WebUI that allows QueryBuilder queries to be written, executed and debugged in real time.”

How it works
In October 2015, Joey wrote a blog post comparing and contrasting the three most prominent query engines in Adobe Experience Manager, but he would admit: “I have never totally gotten my brain wrapped around the Query Builder syntax.” Part of that is because Joey is more geared around the systems side of the house, but I think part of it is also the fact that he has always been very comfortable with XPath.

However, as Joey pointed out on the podcast, there are several things in Adobe Experience Manager that are either easier to do with Query Builder, or—in some cases—just not possible with the other syntaxes. So, if you’re like Joey, and you occasionally struggle with Query Builder syntax—or you just want to be able to more easily interact with the repository while working on your queries—here’s a tool to help. One note we’d like to add: we have found using the “Auto-Query” feature to be pretty sluggish, unless you have very little content in the repo.

Example application
Perhaps you know the subset of node you need to work with, and—since this will be a regular process you need to run—you’re trying to find the most effective way to leverage Query Builder to select those nodes. You could use the Query Editor to fine tune your query, and validate that it gives you the desired set of nodes, before putting it into your code for deployment.

We did a podcast about the CSV Asset Importer in which we talked about the usefulness of this tool. Here is a written breakdown of that podcast for this specific ACS Adobe Experience Manager Tool. Remember, these should only be used in your non-production lanes.

What is it?
From the ACS GitHub page about CSV Asset Importer: “CSV Asset Importer is a tool that accepts a CSV file whose rows represent an Asset to import.”

How it works
When you need to do that initial import of a bunch of Assets for your development work, no one wants to sit there and upload them manually; even creating the correct JCR package structure can be a bit of a pain, especially if you want to import specific items of asset metadata. Thankfully, the ACS guys have created a great tool that allows you to define the list of assets to be imported, their on-disk location and where in the DAM they should end up, as well as their associated metadata, all in a single CSV file. Adobe Experience Manager will then do the hard work of importing the asset, applying the metadata, and executing the required workflows.

Example application
Again, like most of the other ACS AEM Tools, it pretty much just does what it says. We have used it on several projects to import a large batch of assets rather than manually uploading them. If you’re preparing to load a long list of assets into your Adobe Experience Manager instance, this is a very handy way to control the ingestion process. Please pay special attention to the “Important Considerations” mentioned in the documentation.

In July, I had the opportunity to sit down with Bruce Swann, Senior Product Marketing Manager on the Adobe Campaign team, and talk a little bit about Adobe Campaign. We spent time getting the background on it, how it can be used to get people to engage with an organization, how it can be integrated to work with an Adobe Experience Manager site, and what is on the planned schedule for enhancements. Instead of having Joey along with me, I was joined by Stefan Hofmeister, who is an Adobe Certified Expert as a Business Practitioner for Adobe Campaign. Unfortunately the device we were using to record the podcast cut out and so we lost the last part of the conversation, so the podcast ends rather abruptly. Our thanks to Bruce for taking the time to talk to us.

Many Adobe Experience Manager authors and developers are familiar with the concept of a dialog box. In general, customizable AEM components give authors a set of options that they can author when they create or modify a component. The dialog box is the AEM mechanism by which developers enable authors to make these changes, usually without needing specific programming knowledge such as HTML, JavaScript, or CSS.

Dialog boxes, however, can be somewhat of a mystery for the unfamiliar developer, particularly when dealing with data types of the authored properties. How, for example, do I specify that a value of “true” from my dialog box dropdown should be stored as a Boolean instead of a String in the JCR? Or, how can I delete a property when the value passed to it is empty? These are questions that developers new to Adobe Experience Manager (like myself) naturally ask.

In order to solve this problem, we will first look at the technology running under the dialog box hood when we author its properties. Afterward, we will use the insights we gain to build dialog boxes that will appropriately handle our property data types.

The Mighty SlingPostServlet
An essential part of the Adobe Experience Manager architecture is the Apache Sling project, which provides (among other advantages) our RESTful framework for the resources stored in the underlying JCR. As a part of this framework, we have a servlet available to us called the SlingPostServlet, which we will shortly see endows us with powers to make changes to the JCR—assuming the necessary permissions, of course. The essential function of the SlingPostServlet is to create, modify, or delete nodes and their properties in a standard, RESTful way that can be utilized by different parts of AEM. This functionality is fairly well documented on the Sling website (https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html), but I will include a short example here for demonstration.

We will be sending a POST request to modify an existing jcr:content node on the Geometrixx Outdoors page, so pull up your favorite HTTP request client. I’ll be using cURL as my flavor of choice.

Assuming a default installation of AEM including the Sample Content (I’m using Adobe Experience Manager 6.0 Service Pack 2), navigate to /content/geometrixx-outdoors/en/seasonal/jcr:content using CRXDE, and look at this node’s properties under the “Properties” tab. You should see a “hideInNav” property of type “String” and a value of “true”:

We will now construct a request that will hit the SlingPostServlet and change this String’s value to “false” by POSTing to the node we wish to modify. Here is the command that I will run from the terminal:

curl -F hideInNav=false -u admin:admin http://localhost:4502/content/geometrixx-outdoors/en/seasonal/jcr:content

The name of the property, “hideInNav”, immediately follows the -F option, which instructs cURL to send the request as an RFC 2388 form submission. The “-u admin:admin” portion is the credential string needed to log in to my local instance, and the URL represents the location of the resource we wish to modify (specified above). Running this command appropriately modifies the “hideInNav” value to “false” as we can see below:

(As an extra note, AEM also updates the “cq:lastModified” and “cq:lastModifiedBy” properties to match the time and credentials given for the submitted request).

The SlingPostServlet and AEM Dialog Boxes
Great, so now we can perform all these actions on the JCR. But what does that have to do with dialog boxes? The answer: once the dialog box is rendered by Adobe Experience Manager, its purpose is to construct a request to send to the SlingPostServlet, which will appropriately take care of CRUDing (https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) the component properties for us. Let’s go to our Seasonal page and see an example.

Open /content/geometrixx-outdoors/en/seasonal.html in edit mode (either in the classic or touch UI, but this blog post will focus on the touch UI) and pull up the page properties. Now open up your browser’s developer tools and clear all of the requests made in the network tab. Your screen should look something like this in Google Chrome:

After making sure that your browser is recording your network activity, click the “Hide In Navigation” checkbox and save the dialog box. My page reloads when I edit the page, so I’ve set Chrome to preserve my log and filter out all but the XmlHttpRequest requests in my browser (since lots of calls are made to various HTML pages, images, resources, etc.), but you should see a POST request somewhere in the recorded network activity to /content/geometrixx-outdoors/en/seasonal/jcr:content (or _jcr_content) similar to the following:

Click on the “_jcr_content” entry, the first entry on my screen, to see the request details. Here is the output on my machine:

Viola! The dialog box constructed a POST request and submitted it to the Seasonal page’s jcr:content node as expected. Furthermore, if you look at the form data sent in our request you will see some variation of “./hideInNav: true” amongst the data, which sets our “hideInNav” property back to true as expected:

Specifying Data Types with Type Hints
Now we FINALLY return to our JCR data types. We can leverage what we know about AEM’s dialog box functionality to correctly handle the data type of properties we want to manipulate, and we do so by using Sling Type Hints. Type hints are a way of telling the SlingPostServlet how we want to store a particular property in the JCR and are documented here (https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html#typehint). The type hint lives as an additional node underneath the dialog directory. Its “name” property will generally look like this: @TypeHint, such as “./myproperty@TypeHint”, and its “value” property: “”, such as “Boolean”. (To see all of the defined types, open the “Type” dropdown at the bottom of the CRXDE screen.)

As mentioned at the beginning of this post, sometimes we want our true/false values to be saved as Booleans instead of Strings. Let’s go back one more time to our example and attempt to achieve this with an Adobe Experience Manager component. There should be a simple component named “Title” at /apps/geometrixx-outdoors/components/title. Or, if there isn’t, you can grab the title component from the libs directory at /libs/foundation/components/title and copy that to the apps directory instead. Let’s add a Granite UI Select Component to the dialog box and call it “booleanField”. In CRXDE, create a new “nt:unstructured” node and give it the following properties:

Now we will add the items to populate the dropdown. Create another new “nt:unstructured” node called “items”, and add two nodes beneath the “items” node called “true” and “false”. Here are the “true” option properties:

The “false” properties are similar: enter “False Value” for the “text” property and “false” for the “value” property.

Now return to the Seasonal page and author a new “Title” component from the “General” category (this is the default category for the Geometrixx Title component) somewhere on the page. Open up the component’s dialog box and you should see something similar to this:

We see our “Boolean Field Option” property as a dropdown at the bottom of the dialog properties. So far so good! Change the dropdown value and click the checkbox to save the changes. Now let’s go look at the properties of our new Boolean field:

Whoops. You can see the “booleanField” property listed at the top of the properties list, and it has been given a String type. But not to worry—type hints to the rescue! Let’s add our Boolean type hint. Create another node in the dialog definition, “booleanFieldTypeHint”, of type “nt:unstructured” at the same level as “booleanField”. It will have the following properties:

We can see the “name” property is “./booleanField@TypeHint” and the value is “Boolean”. It has a sling resource type of Granite UI “hidden”, which tells Adobe Experience Manager that it shouldn’t be visible to authors in the dialog box. The “ignoreData” property tells us that the “value” property of this node should always be “Boolean”, regardless of whatever value may find its way into the submitted form dialog under the name of “booleanFieldTypeHint”.

Now, delete the “booleanField” property from the title content node. (Note that this is the location of the specific title component authored on the Seasonal page, not the dialog box node! For example, on my machine, the path to my title content node is /content/geometrixx-outdoors/en/seasonal/jcr:content/sidebar/title_737116960.) Let’s try authoring the property again with our type hint in place. Open up the title dialog box and change our custom property value in the dropdown again. Here is the resulting request that my AEM instance sends when I save the changed dialog box:

In the form data section we see our “./booleanField” value of “false” and a new property that matches the type hint we just created: “./booleanFieldTypeHint” with a value of “Boolean”, as expected. Now if we go back to CRXDE and look at the properties for our title component, there should be a change to the data type and the value of “booleanField”:

As desired, our “booleanField” property at the top now has a “Type” value of “Boolean”! The JCR will now interpret this property as a Boolean instead of a String, as desired.

There’s lots more you can do with type hints. Make sure to check out the documentation and try using them in your own dialog boxes.

That’s it! As always, feel free to email us with any questions or comments to info@aempodcast.com. Happy hinting!