DocumentationAEM 6.4Developing Guide

Cloud Service Configurations cloud-service-configurations

Last update: Wed May 03 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Developer
CAUTION
AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.

Configurations are designed to provide the logic and structure for storing service configurations.

You can extend the existing instances to create your own configurations.

Concepts concepts

The principles used in developing the configurations have been based on the following concepts:

  • Services/Adapters are used to retrieve the configuration(s).
  • Configurations (e.g. properties/paragraphs) are inherited from the parent(s).
  • Referenced from analytics node(s) by path.
  • Easily extensible.
  • Has the flexibility to cater for more complex configurations, such as Adobe Analytics.
  • Support for dependencies (e.g. Adobe Analytics plugins need a Adobe Analytics configuration).

Structure structure

The base path of the configurations is:

/etc/cloudservices.

For each type of configuration a template and a component will be provided.This makes it possible to have configuration templates that can fulfil most needs after being customized.

To provide a configuration for a new services you need to:

  • create a servicepage in

    /etc/cloudservices

  • under this:

    • a configuration template
    • a configuration component

The template and component must inherit the sling:resourceSuperType from the base template:

cq/cloudserviceconfigs/templates/configpage

or base component respectively

cq/cloudserviceconfigs/components/configpage

The service provider should also provide the service page:

/etc/cloudservices/<service-name>

Template template

Your template will extend the base template:

cq/cloudserviceconfigs/templates/configpage

and define a resourceType that points to the custom component.

/libs/cq/analytics/templates/sitecatalyst
sling:resourceSuperType = cq/cloudserviceconfigs/templates/configpage
allowedChildren = /libs/cq/analytics/templates/sitecatalyst
allowedPaths = /etc/cloudservices/analytics/*, /etc/cloudservices/analytics/.*
componentReference = cq/analytics/components/sitecatalyst
jcr:content/
cq:designPath = /etc/designs/cloudservices
sling:resourceType = cq/analytics/components/sitecatalystpage

/libs/cq/analytics/templates/generictracker
sling:resourceSuperType = cq/cloudservices/templates/configpage
allowedChildren = /libs/cq/analytics/templates/generictracker
allowedPaths = /etc/cloudservices/analytics/*, /etc/cloudservices/analytics/.*
jcr:content/
cq:designPath = /etc/designs/cloudservices
sling:resourceType = cq/analytics/components/generictrackerpage

Components components

Your component should extend the base component:

cq/cloudserviceconfigs/templates/configpage

/libs/cq/analytics/components/sitecatalystpage

/libs/cq/analytics/components/generictrackerpage

After setting up your template and component you can add your configuration by adding subpages under:

/etc/cloudservices/<service-name>

Content Model content-model

The content model is stored as cq:Page under:

/etc/cloudservices/<service-name>(/*)

/etc/cloudservices
/etc/cloudservices/service-name
/etc/cloudservices/service-name/config
/etc/cloudservices/service-name/config/inherited-config

The configurations are stored under the subnode jcr:content.

  • Fixed properties, defined in a dialog should be stored on the jcr:node directly.
  • Dynamic elements (using parsys or iparsys) use a subnode to store the component data.
/etc/cloudservices/service/config/jcr:content as nt:unstructured
propertyname
*
par/component/ as cq:Component
propertyname
*

API api

For reference documentation on the API see com.day.cq.wcm.webservicesupport.

AEM Integration aem-integration

Available services are listed in the Cloud Services tab of the Page Properties dialog (of any page that inherits from foundation/components/page or wcm/mobile/components/page).

The tab also provides:

  • a link to the location where you can enable the service
  • choose a configuration (subnode of the service) from a path field

Password Encryption password-encryption

When storing user credentials for the service, all passwords should be encrypted.

You can achieve this by adding a hidden form field. This field should have the annotation @Encrypted in the property name; i.e. for the password field the name would be written as:

password@Encrypted

The property will then be automatically encrypted (using the CryptoSupport service) by the EncryptionPostProcessor.

NOTE
This is similar to the standard [SlingPostServlet](https://sling.apache.org/site/manipulating-content-the-slingpostservlet-servletspost.html) annotations.
NOTE
By default the EcryptionPostProcessor only encrypts POST requests made to /etc/cloudservices.

Additional Properties for Service Page jcr:content Nodes additional-properties-for-service-page-jcr-content-nodes

Property
Description
componentReference
Reference path to a component to be automatically included in the page.
This is used for additional functionality and JS inclusions.
This includes the component on the page where
cq/cloudserviceconfigs/components/servicecomponents
is included (normally before the body tag).
In case the of Analytics and Target we use this to include additional functionality, such as JavaScript calls to track visitor behavior.
description
Short description of the service.
descriptionExtended
Extended description of the service.
ranking
Service ranking for use in listings.
selectableChildren
Filter for displaying configurations in page properties dialog.
serviceUrl
URL to service website.
serviceUrlLabel
Label for service URL.
thumbnailPath
Path to thumbnail for service.
visible
Visibility in page properties dialog; visible by default (optional)

Use Cases use-cases

These services are provided by default:

NOTE
See also Creating a Custom Cloud Service.
recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e