Role definitions

Example role definitions:
https://github.com/wcm-io-devops/conga/tree/develop/tooling/conga-maven-plugin/src/it/example/definitions/src/main/roles

The filename of the role YAML file is the role name.

The documentation of all role and file configuration options can be found in the
Role Model API documentation.

inherits:
- role: superRole

Environment definitions

Example environment definitions:
https://github.com/wcm-io-devops/conga/tree/develop/tooling/conga-maven-plugin/src/it/example/environments/src/main/environments

The filename of the environment YAML file is the environment name.

The documentation of all environment and node configuration options can be found in the
Environment Model API documentation.

Configuration parameter maps

On nearly every element within the YAML structure configuration parameter maps can be applied. Example:

config:
  param1: value1
  group1:
    param11: 5
    param12: true
  list1:
  - listValue1
  - listValue2

Parameter names can be nested in object in any depth. Lists are supported as well.

For nested groups a short notation is supported using a “.” notation.

This example is equivalent to the previous one:

config:
  param1: value1
  group1.param11: 5
  group1.param12: true
  list1:
  - listValue1
  - listValue2

Within the configuration parameters maps other parameters can be referenced using a variable notation. Example: ${group1.param1}. Nested variable references are supported, just make sure you define no cyclic dependencies.

Configuration parameter maps are inherited to “deeper levels” within the YAML structure, and the maps are merged on each level. The configuration parameters on the “deeper levels” overwrite the parameters from the higher level.

Inheritance order (higher number has higher precedence):

1. Global configuration parameters from role definition
2. Configuration from role variant definition
   • If multiple variants are assigned to a node/role their configs are merged, first variants have higher precedence
3. Global configuration from environment
4. Node configuration from environment
5. Global role configuration from environment
6. Role configuration from node
7. Variant configuration from node
8. Configuration from multiply plugins, e.g. the tenant-specific configuration

There is a special support when merging list parameter. By default a list value on a deeper lever overwrites a list inherited from a parameter map on a higher level completely. If you insert the keyword _merge_ as list item on either of the list values, they are merged and the special keyword entry is removed.

Variable references

You can reference configuration parameter values defined in the environment, or as default values in the roles using this variable syntax:

${myvariable}
${mygroup.myvariable}

If no value is defined for this variable, the configuration generation fails. It is recommended to define a default value in the role definition for each variable it uses. An alternative is to define a default value within the variable reference like this:

${myvariable:defaultValue}
${myvariable:defaultListItem1,item2,item3}

You can reference values from external source via value providers (see Extensibility model), e.g. from the “System Parameter Value Provider”:

${system::my.system.parameter}
${system::my.system.parameter:defaultValue}

Instead of single variable expression you can also use Java Expression Language (JEXL). This cannot be combined with value provider expressions or default values. Examples:

${myvariable1 + '/' + myvariable2}
${mygroup.myvariable == 'expected_value'}
${mynumber + 1}
${new('java.text.DecimalFormat','000').format(multiplyIndex)}
${stringUtils:join(listParam,'|')}

When you escape the dollar sign with a backslash the variable is untouched by CONGA:

\${my-static-string}

Iterate over variable list values

When reading a variable with list of values from external source via a value provider, it may be required to generate a list of configuration statements within an environment definition. In this case the _iterate_ keyword can be used.

Example from an environment definition file:

- node: author1
  roles:
  - role: aem-cms
    variant: aem-author
  config:
    replication.author.publishTargets:
      _iterate_: ${system::publishTransportUrls}
      name: publish${_itemIndex_}
      host: ${_item_}
      transportUser: ...
      transportPassword: ...

In this example a list of hostnames/transport URLs is read from system parameter publishTransportUrls. For each item a configuration block is generated. The following implicit variables can be references inside the ‘iterate’ block:

• _item_: The list item value
• _itemIndex_ The list item index (starting with 0)

The example above results in an environment configuration like this when the configuration is generated:

- node: author1
  roles:
  - role: aem-cms
    variant: aem-author
  config:
    replication.author.publishTargets:
    - name: publish0
      host: http://publish1:4503
      transportUser: ...
      transportPassword: ...
    - name: publish1
      host: http://publish2:4503
      transportUser: ...
      transportPassword: ...

Default context properties

Additionally to the variables defined in the configuration parameter maps a set of default context properties are defined automatically by CONGA and merged with the parameter maps: