Items Render¶

Items Render target are meant to generate a configuration item and using a smart duplication mechanism. This aim to reduce copy/past necessities and provide a management mechanism to easily maintains and update those item duplications. This target has an item granularity, this mean that it’s not possible to duplicate only a single file on a destination directory. the Evaluation rules can be used to alter a generic item.

For example if an integrator want to duplicate a device over his final configuration, he can create a template configuration in folder /templates/sources:

modules/
root/
templates/
└─ sources/
   └─ itemToCopy/
      ├─ childItem/
      ├─ value.ospp
      └─ owner.modbus

The final state after playbook target’s run may give the following result:

modules/
root/
├─ device/
│  ├─ childItem/
│  ├─ value.ospp
│  └─ owner.modbus
├─ secondDevice/
│  ├─ childItem/
│  ├─ value.ospp
│  └─ owner.modbus
templates/
└─ sources/
   └─ itemToCopy/
      ├─ childItem/
      ├─ value.ospp
      └─ owner.modbus

Item called here itemToCopy has been duplicate over inside configuration’s tree.

The Inventory is used to describe the duplication process of itemToCopy. Additional configuration, variables and files may be provided during duplication through custom rules.

Items Render process the Inventory line by line and generate the requested configuration path. Following steps are done in order to achieve the final result.

Parse first line of the Inventory.
Extract source and destination item.
Extract variables and variables files.
Parse rules.

Extract variables and variables files.

Generate modifications.

Parse parents rules if necessary.

Update variables and variables files.
Generate list of files to create.
Apply rules.
Write files in the final configuration.

Target Definition¶

The target are define by the schema.

{
  "type": "ItemsRender",
  "source": "templates/inventory/datas.csv",
  "fileRenderContext": {}
}

Sometimes Items source folder may contains some file to render individually. In this case, the target will automatically create a FileRender target to be able to render this file. Attribute fileRenderContext may be use the same way a import attribute from FileRender target for context injection.

The following sample inject the content of additional.csv inside the FileRender context through the variable additional

{
  "type": "ItemsRender",
  "source": "templates/inventory/datas.csv",
  "fileRenderContext":{
    "additional": "templates/inventory/additional.csv"
  }
}

And can be used in .nunjucks template:

{% for test in additional %}
  {{ test.myVarName }}
{% endfor %}

Evaluation rules¶

Warning

Each rule is fully executed before process to next one.

Rules files can be used to alter some part of the copy done by the Inventory. For example, exclude a file for a location that is not in service yet to avoid triggering the alarms.

It has the following possibilities:

Add and override variables.

Append new variables file.

Add/Exclude node.

Add/Exclude file.

Import rules from one or multiple parents.

They are define in a json file.

{
    "variablesFiles": [
        "root.templates.site-fribourg",
        "root.templates.site-firstfloor"
    ],
    "variables": {
        "value1": "test",
        "number": 10.0
    },
    "parentRules": [
        "templates.default-rule"
    ],
    "rules": [
        {
            "type" : "ExcludeNode",
            "item": "root.device-type-b.sub-device"
        },
        {
            "type" : "ExcludeFile",
            "path": "root/device-type-c/callback.ospp"
        },
        {
            "type" : "AddFile",
            "source": "template/modbus/callback-default/callback.ospp",
            "destination": "root.device-type-a.sub-device"
        },
        {
            "type" : "AddNode",
            "source": "template.modbus.sup-energy",
            "destination": "root.device-type-a.sub-device"
        }
    ]
}

Type of rules¶

The rules are divided into four kinds that allow to add and remove a specific file or node (aka Item) from a source. The source can contain multiple sub-item.

Kind	Description	Parameters
`ExcludeNode`	Exclude a source `itemId` from the configuration.	`item`: the source `itemId` to exclude.
`AddNode`	Add a node to the configuration from a source `itemId` to a destination `itemId`.	`source`: the source `itemId` to add. `destination`: the destination `itemId`.
`ExcludeFile`	Exclude a source file `path` from the configuration.	`path`: the source `path` to exclude.
`AddFile`	Add a file to the configuration from a source `path` to a destination `path`.	`source`: the source `path` to add. `destination`: the destination `path`.

Note

A path is define a the relative unix path (/ separator) from the root of the OnSphere git.

Variables override rules¶

Variables¶

The variables define inside a rule are overridden by the one inside the Inventory and the one define by the rule importing it.

VariablesFiles¶

The variables.ospp define in variablesFiles are not evaluated but are simply append to the current variablesFiles list which is injected into the generated files. See Variables files for more information.