Extending Parameterized Templates

Parameterized templates contain props objects with attributes which can be set by the parent template. The same mechanism is used for robust template extensions -- for example, extensions that don't rely on knowledge of the inner structure of a template. A template extension can define values for these props objects, which are merged into the template; that’s why the artifact is called templatePropsExtension. This extension has a props object under which a dictionary of prop names and values are defined. For example:

{
  "kind": "templatePropsExtension",
  "name": "k8s:cluster-ecpRelationshipMap",
  "props": {
    "elements": [
      {
        "index": -1,
        "value": {
          "key": "example",
          "path": "out.to(spacefleet:starship)",
          "entityAttribute": "starship.registry",
          "iconName": "AgentType.Appd"
        }
      }
    ]
  }
}

In this example:

• elements is the array of Relationships map elements. Each of these elements has a preferred index and a value, where the value specifies the relative path of the scope (K8s clusters) to the navigable entities.
• entityAttribute specifies which attribute to display under a Relationships map entry if there is only one entity (instance).

Preparing Parameterized Templates for Extensions

In principle, a templatePropsExtension works with every parameterized template. In practice, the values set for individual props by the parent element and extensions compete with each other. If not otherwise specified, the default values (specified in the template itself) are overridden by the extensions (applied in no particular order; the last one overrides the value of preceding ones) and finally by the props object passed by the parent element. This might not be the appropriate way of merging the props in many use cases. Therefore, a parameterized template can also specify a propDefs object containing the merging strategy for every individual parameter (prop).

The following merging strategies are provided:

• override (default)
• concat (options: sort, distinct, automatic flattening)
• merge
• custom (options: "JSONata expression")

The input for the merging strategy is an array of property sets (each set being a dictionary of prop names and values. The first element is always the props specified by the template itself and the last element is always the property set specified by the parent template). In between are the property sets specified by the extensions.

override

Property definitions:

"propDefs": {
 "foo": { "reduce": "override"},
 "bar": { "reduce": "override"},
 "baz": { "reduce": "override"},
 "qux": { "reduce": "override"}
}

Property sets (input):

# propSets[0]
foo: 1
bar: [22]
baz: [[3]]
qux: 4
---
# propSets[1]
foo: 11
bar: [22]
baz: [33]
qux: null

Merged property set:

foo: 11
bar: [22]
baz: [33]
qux: 4

concat

The concat strategy is used to merge arrays. It includes the automatic flattening of arrays. For this strategy, additional options can be specified:

• Order: An array of paths (such as lodash prop paths) to pluck sorting keys from
• Distinct: Decide if props should have unique values

Property definitions:

"propDefs": {
 "foo": { "reduce": "concat"},
 "bar": { "reduce": "concat"},
 "baz": { "reduce": "concat"},
 "qux": { "reduce": "concat"}
}

Property sets (input):

# propSets[0]
foo: 1
bar: [22]
baz: [[3]]
qux: 4
---
# propSets[1]
foo: 11
bar: [22]
baz: [33]
qux: null

For this strategy, the output is:

foo: [1, 11]
bar: [22, 22]
baz: [3, 33]
qux: [4]

Property definitions:

"propDefs": {
 "foo": { "reduce": "concat", "distinct": true},
 "bar": { "reduce": "concat", "distinct": true},
 "baz": { "reduce": "concat", "distinct": true},
 "qux": { "reduce": "concat", "distinct": true}
}

Output:

foo: [1, 11]
bar: [22]
baz: [3, 33]
qux: [4]

custom

Property definitions:

"propDefs": {
  "foo": { "reduce": { "type": "custom", "expression": "$average(**)" } }
}

Property sets (input):

# propSets[0]
foo: 2
---
# propSets[1]
foo: [3, 4]

Output:

foo: 3