CONGA - Extensions | CONGA AEM Plugin

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.