Administrators often need to automate or simplify common tasks within any system. In Adobe Experience Manager (AEM), managing users, installing packages, and managing OSGi bundles are some of the tasks where automation is commonly required. Because of the RESTful nature of the Sling framework upon which AEM is built, most of the tasks can be reduced to a URL call. cURL can be used to execute such URL calls and can be proved as a useful tool for automation inside an AEM environment.

What is cURL

cURL stands for Client for URL and is an open-source command-line tool used to perform URL manipulations. It supports a wide range of internet protocols including HTTP, HTTPS, FTP, FTPS, SCP, SFTP, TFTP, LDAP, DAP, DICT, TELNET, FILE, IMAP, POP3, SMTP, and RTSP. Originally released in 1997, cURL is a well-established and widely-used tool for providing or receiving data using the URL syntax

Installation

cURL comes by default in most of the systems, however, it can be downloaded and installed from the link here

Windows users need to ensure that they have appended the environment variable ‘path’ with the path of the bin where cURL is installed. The stepwise process is mentioned below.

1. Open the Start Search, type in “env”, and choose “Edit the system environment variables”.
2. Click the “Environment Variable” button.
3. Under the “System Variables” section (the lower half), find the row with “Path” in the first column, and click edit.
4. The “Edit environment variable” UI will appear. Click on “New” and type in the new path you want to add.

cURL for AEM

Since AEM follows REST architecture, cURL can execute most tasks using a URL call. cURL can be handy when it comes to content manipulation tasks such as activating pages, starting workflows and operational tasks such as package management and managing users. In addition you can create your own cURL commands for most of the tasks in AEM. The official link for some common AEM cURL commands is here

A cheat sheet is also available for reference.

Building a cURL command for AEM

cURL commands can be built for most operations in AEM such as triggering workflows, checking OSGi configurations, triggering JMX commands, creating replication agents, etc. To find the exact command needed for a particular operation, use the developer tools in your browser to capture the POST call to the server when you perform the AEM operation manually. Now, let’s see how to create the cURL command for giving path specific read/modify access to a user.

1. Prepare the action you wish to invoke within AEM. In our case, we have proceeded to the /useradmin page to manage users.

1. Go to the developer console or Right click and select inspect and then go to the network tab.

1. Select the permissions that you want to give to the user for the specified path and then click save. Here, we will proceed with read/modify permissions for /etc path (observe the POST call).

1. Copy the URL from the POST call in the header section.

Request payload from request section. This will be the data parameter for our cURL command.

1. Execute the cURL command via command line and view the response.

    curl -u admin:admin -d
    'authorizableld=test&changelog=path:%2Fetc,read:true,modify:true,create:false,delete:false,acl read:false,acl_edit:false,replicate:false&_charset_=utf-8' -X POST
    'http://localhost:4502/.cqactions.html'

Moving beyond cURL

Although cURL is the go-to tool for administration API testing in AEM and has a lot of documentation established around it, it has its flaws in terms of automation and dependency to shell. These flaws can create obstacles while writing server- independent and complex scripts.

Challenges with cURL

• Inconsistent response payload types: cURL response types vary in terms of usage. This creates a lack of uniformity when writing scripts that utilize response payloads. As seen in the last example above, the response for updating permission was in HTML. However, the response for activating an OSGi bundle, for example, is in JSON.

  

  And the response for listing packages in crx is in XML.

  

• Unreliable status codes: Some of the status codes that are returned as a response are occasionally unreliable. Here are some examples:

  • http 200 with empty response body when authentication is invalid
  • http 200 with error message in html response body when old password is incorrect

• Serverless: cURL is dependent on access to shell and lacks integration with Serverless frameworks.

The Way Forward: OpenAPI (Swagger) for AEM

Swagger AEM is an OpenAPI specification for Adobe Experience Manager, which can be used to generate API clients in 30 programming languages. These API clients, in turn, are useful for integrating AEM with a number of technology stacks. From setting OSGI configuration using provisioning tools such as Puppet, to deploying AEM packages using voice via Google Assistant. The possibilities are endless. Ruby_aem is one option that can solve the cURL AEM challenges.

What makes Ruby_aem a viable solution?

1. Resource Oriented Design
2. Further abstraction away from endpoints
3. Error and response objects
4. Additional custom APIs

Installation

    $ sudo apt update
    $ sudo apt install ruby-dev 
    $ sudo apt install gem 
    $ sudo gem install ruby_aem

Result Handling

Ruby_aem allows for much better result handling due to its uniform response payloads which are parsed beforehand. Also, it is endpoint free.

    require 'ruby_aem'

    aem = RubyAem::Aem.new({
        username: 'admin', 
        password: 'admin', 
        protocol: 'http', 
        host: 'localhost', 
        port: 4502, 
        timeout: 300, 
        verify_ssl: true, 
        debug: false
    })

    #user to be assigned

    user = aem.user ('/home/users/V/, 'test')
    #check existence of user
    result = user.exists

    #if user exists, then change permissions 
    if result.data == true
        result = user.set_permission("/etc', 'read:true,modify:true')
        puts result.message 
    end

Error Handling

Better error and edge case handling allows us to write more robust scripts. Additionally, unlike cURL, ruby is a first class programming language which gives us much more flexibility and freedom.

    require 'ruby_aem'
    aem = RubyAem::Aem.new({
        username: 'admin', 
        password: 'admin', 
        protocol: 'http', 
        host: 'localhost', 
        port: 4502, 
        timeout: 300, 
        verify_ssl: true, 
        debug: false
    })

    begin
    #user to be assigned
        user = aem.user(/home/users/V/', 'test')
        result = user.set_permission('/etc, 'read:false,modify:false')
    rescue RubyAem::Error => err 
        puts err.message
        puts err.result.data 
    end

Serverless

Ruby_aem is only part of the available client library support for Swagger_aem. Swagger_aem also houses support for java, python and javascript for AEM. This allows us to move forward from the dependency on shell.

Key Features of Ruby_aem

• Wait until login page is ready
• Wait until AEM health check is passed
• Bundle start, stop
• Configuration property create
• Replication, reverse replication, and flush agents create, update, delete
• User and group create and delete
• Add user and group to a group
• Node create and delete
• Package create, update, delete, upload, install, uninstall, replicate, list, versions
• Path activate
• Repository block, unblock

Conclusion

All in all, cURL and Ruby_aem both have their uses in AEM. Although cURL is a much easier tool to pick up on the go and use for testing out APIs or hitting URLs, it is still lacking in some areas. For complex automation, Ruby_aem provides a more comprehensive pool of utilities.