The CONGA AEM Plugin extends CONGA using its extensibility model.

Provided Plugins

File plugins:

Plugin name File name(s) File Header Validator Escaping Post Processor
any .any X X X
aem-contentpackage .json X X
aem-contentpackage-osgiconfig .provisioning, .txt X X
aem-contentpackage-properties .zip X

Please note: Files with the extension txt are only managed as provisioning files if the contain the string "[feature " (heuristic).

Generating AEM Content Packages

The CONGA AEM Plugin provides two post processor plugins that generate AEM Content Packages (ZIP files with JCR XML files describing a JCR content structure). These content packages can be imported into a AEM instance using the CRX Package Manager.

The plugin aem-contentpackage generates a content package out of a JSON file. This JSON files contains JCR content as produced by the Sling GET Servlet.

The plugin aem-contentpackage-osgiconfig generates a content package containing OSGI configurations out of a Sling Provisioning file.

The Sling Provisioning Model file format is described on the Sling Website. It is a compact format that allows to define features with bundles and configurations for a Sling-based distribution. The CONGA AEM Plugin uses only the configurations and ignores all other parts of the file.

Both post processor plugins support a set of options that allow further configuration of the generated content package:

Property Description
contentPackage.group Group name for content package
contentPackage.name Package name for content package
contentPackage.description Description for content package
contentPackage.version Version for content package
contentPackage.rootPath Root path for the content package
contentPackage.filters Contains list with filter definitions, optionally with include/exclude rules. If not defined a simple filter rule is derived from the contentPackage.rootPath property.
contentPackage.acHandling How to apply ACLs that are contained in the content package. Possible values: ignore (default), overwrite, merge, merge_preserve, clear.
contentPackage.thumbnailImage URL to thumbnail PNG image to be used for the content package. URL file plugin prefixes can be used (e.g. classpath:).
contentPackage.files List of additional binary files to be included in content package. For each file you have to specify a path property (target path), and for the source an url property for an external file, or a file and dir property for a file that was generated by CONGA. Instead of file your can also use fileMath to include multiple files matching this pattern. If the file should be deleted after the inclusion you can additionally specify delete: true.
contentPackage.properties Defines map with additional custom properties for package metadata.
contentPackage.packageType Defines the packageType for the content package. Uses for FileVault validation of the package.
contentPackage.requiresRoot Package requires root.
contentPackage.requiresRestart Package requires restart.
contentPackage.allowIndexDefinitions Package allows index definitions.

Example for defining package properties with a set of filters:

# Define a AEM content package with some JCR content (Sling Mapping Example)
- file: sling-mapping.json
  dir: packages
  template: sling-mapping.json.hbs
  # Post-processors apply further actions after generation the file
  postProcessors:
  - aem-contentpackage
  postProcessorOptions:
    contentPackage:
      name: mapping-sample
      rootPath: /etc/map/http
      filters:
      - filter: /etc/map/http
        rules:
        - rule: exclude
          pattern: /etc/map/http
        - rule: include
          pattern: /etc/map/http/.*
        - rule: exclude
          pattern: /etc/map/http/AppMeasurementBridge

Example for additionally adding binary files to the content package:

# Define a AEM content package with some JCR content
- file: my-package.json
  dir: packages
  template: my-package.json.hbs
  # Post-processors apply further actions after generation the file
  postProcessors:
  - aem-contentpackage
  postProcessorOptions:
    contentPackage:
      name: my-package
      rootPath: /content/files
      files:
      # Add a static file from the class paths (or other URLs)
      - url: classpath:/my-resources/file1.txt
        path: /content/files/file1.txt
      # Add a file that was generated by CONGA (delete after inclusion in package)
      - file: generated-file.txt
        dir: generated-files
        path: /content/files/generated-file.txt
        delete: true
      # Add a set file that were generated by CONGA (delete after inclusion in package)
      - fileMatch: file_(.*)\.txt
        dir: generated-files
        path: /content/files/$1.txt
        delete: true

Validating AEM Content Packages

AEM content packages generated by aem-contentpackage or aem-contentpackage-osgiconfig are validated automatically using the FileVault validation. The type of validation relies on the packageType that is set for this package (and is disabled if no package type is set). The validation and configuration is similar to that of the Jackrabbit FileVault Package Maven Plugin.

Example for reconfiguring a FileVault filter:

  validatorOptions:
    contentPackage.validatorsSettings:
      jackrabbit-filter:
        options:
          validRoots: /etc/replication

Example for disabling a FileVault filter:

  validatorOptions:
    contentPackage.validatorsSettings:
      jackrabbit-filter:
        isDisabled: true

See FileVault validation for all available filters and options.

Post-processing AEM Content Packages

With the post-processor plugin aem-contentpackage-properties is applied automatically to all ZIP files manged by CONGA. The properties contained in the AEM package are extracted and included per file in a property aemContentPackageProperties in the model YAML.

The model YAML file can be exported during CONGA generation and provides the necessary runtime information for deployment tools like Ansible.

Back to top

Version: 1.13.1-SNAPSHOT. Last Published: 2020-09-15.