Adobe Experience Manager's Sling RepoInit: Have You Tried It Yet?

November 16, 2021
Lead Developer

There’s a lot to do when it comes to managing the initial repository state in Adobe Experience Manager (AEM). Keeping all the environments in sync with the required basic code, content, and configuration is a challenge. So is ensuring a consistent local setup for all the developers on a project—content, users and groups, node structures, configurations, and more.

Enter - Sling RepoInit! 

What Is Sling RepoInit?

Sling RepoInit is a mechanism used by Sling for base repository initialization. It also includes the ability to register configurations making it available to projects to further configure the repository. It is implemented as a Domain Specific Language (DSL) with a parser and JCR implementation.

With immutable instances becoming the norm, it has taken on a more important role. With RepoInit you can write instructions or scripts that define JCR structures, ranging from common node structures like folder trees to users, service users, groups, and ACL definitions. This is useful, especially for initialization and content migration purposes.

Why Sling RepoInit?

RepoInit operations are fast and atomic.

With RepoInit scripts, instructions are checked against the current state and executed only if needed. All this happens when the RepositoryInitializer in the JCR RepoInit Bundle initializes, thereby ensuring all required JCR structures exist by the time code is executed.

Imagine—no more application failures and exceptions due to missing resources!

RepoInit operations are always additive, except for a few cases which allow removal of Users, Service Users, and Groups.

Explicit permissions are not needed to run the RepoInit scripts. They have implicit permissions to perform all actions defined per the scripts.

With RepoInit, the repository-related configurations can be managed through code. This is a bonus, especially if you are developing for AEMaaCS.

It is possible to validate repoinit statements on a local development environment at runtime since they will be executed when the OSGi configuration gets registered.

What Do I Need for Sling RepoInit?

To be able to use all the cool stuff as detailed in their documentation here, Sling RepoInit requires AEM 6.5 SP4+ or AEM as a Cloud Service.

Tip: AEM 6.5 includes an older version of Sling RepoInit. If you find yourself stuck not being able to implement one of the cool features as described in the link above, consider upgrading one of the two Repoinit bundles. You can navigate to /system/console/bundles and look for the version information of the following bundles:

  • Apache Sling Repoinit JCR (org.apache.sling.jcr.repoinit)
  • Apache Sling Repoinit Parser (org.apache.sling.repoinit.parser)  

How Do I Define a RepoInit OSGi Configuration?

Like the Sling Logging Logger service, it is implemented as an OSGi factory configuration. To configure a new RepoInit script:

Create OSGi Service Factory Configuration for PID org.apache.sling.jcr.repoinit.RepositoryInitializer

For example:

     /apps/my-demo-site/config/org.apache.sling.jcr.repoinit.RepositoryInitializer~my-demo-site

Such configurations have two optional fields:

""references"
  • References - A multi-value field with each value providing the URL (as a String) of raw repoinit statements.
  • Scripts - A multi-value field with each value providing repoinit statements as plain text in a String.

Using one of the two options mentioned above, you can either reference a file or add a script. Personally, I find the script approach more convenient and that is what we would be discussing more on. 

The format of OSGi configuration itself can be JSON-based using the .cfg.json format or XML-based using the .xml format. For example:

/apps/my-app/config/org.apache.sling.jcr.repoinit.RepositoryInitializer~my-demo-site.cfg.json
{
    "scripts": [
        "create service user service-user1",
        "set ACL for service-user1\n\tallow jcr:read on /content/my-demo-site\nend",
        "set ACL for service-user1\n\tallow jcr:versionManagement,jcr:modifyProperties,jcr:read,jcr:addChildNodes,jcr:lockManagement,jcr:nodeTypeManagement on /apps/my-demo-site/clientlibs/clientlib-base\nend"
    ]
}
/apps/my-demo-site/config/org.apache.sling.jcr.repoinit.RepositoryInitializer~my-demo-site.xml
<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
          xmlns:jcr="http://www.jcp.org/jcr/1.0" jcr:primaryType="sling:OsgiConfig"
          references="[]"
      scripts="[
        create service user service-user1,
        set ACL for service-user1&#010;
            allow jcr:read on /content/my-demo-site&#010;
        end,
        set ACL for service-user1&#010;
            allow jcr:versionManagement\,jcr:modifyProperties\,jcr:read\,jcr:addChildNodes\,jcr:lockManagement\,jcr:nodeTypeManagement on /apps/my-demo-site/clientlibs/clientlib-base&#010;
        end
      ]"/>

A few tips to keep in mind as you define your RepoInit OSGi configuration:

  • In AEMaaCS, .cfg.json format supersedes other formats. 
  • While defining the OSGi configuration with .xml format, use ASCII encoded value “&#010;” for a new-line character. 
  • You can tail logs and confirm that each command as defined the repoinit script is executed line by line.
  • RepoInit Logging : Add an INFO logger for the packages:
    • org.apache.sling.repoinit 
    • org.apache.sling.jcr.repoinit

Wrapping It Up

Sling RepoInit is a great tool for helping with initial setup of project-specific context. We hope after reading this article you have a better understanding of what this tool does and why it will be useful for assisting with writing instructions or scripts that define JCR structures. 

For more on Sling RepoInit check out our next article, Adobe Experience Manager’s Sling RepoInit: When Should You Use It?

References and Resources: 

Part one of our Adobe Experience Manager’s Sling RepoInit series.