File Render

Concept

This kind of template offer the capability of creating single file, powered by nunjunks. This feature is different from the items render feature that is list oriented.

Use-case

• Creating complex file who is not depending of an inventory

• Create single file based on inventory

• Creating dashboard with widget configured from inventory

• Creating dynamic script

Usage

See schema schema and documentation for configuration details of *.playbook configuration file.

[
    {
        "type": "FileRender",
        "generation": [
            {
                "source": "templates/sources/example-1/dashboard/dashboard.view.nunjucks",
                "destination": "root.dashboard"
            }
        ],
        "import": {
            "devicesList": "templates/inventory/data.csv"
        }
    },
    {
        "type": "FileRender",
        "generation": [
            {
                "source": "templates/sources/example-1/dashboard/dashboard.web.nunjucks",
                "destination": "root.dashboard"
            }
        ],
        "import": {}
    },
    {
        "type": "ItemsRender",
        "source": "templates/inventory/data.csv",
        "fileRenderContext": {}
    }
]

Source File

This target require a specific source file that contain template’s markers. Those markers will be resolved using a context (see Context gathering) to render a final valid configuration file.

Important

Templates rendering source files names has to end with a .nunjucks extension.

Context gathering

File Render’s target use a context to hold all variables and expose them during template’s logical resolution. This mean that you can provide your own inventory that contains serval variables and in a script. Target property import is an object that will be exposed directly in context.

See schema for up-to-date documentation.

The context is build from variable definition see variable order for details. The context is the list of variables made available on the .nunjunks file.

Composer Nunjucks environment

Nunjucks allow custom environnement to be define to add customs filters and function. The composer expose his own nunjucks filters .

Filter	Argument	Description	Example
innerJoin	inventory, entry, foreignKey, property	This filter combines entries from two inventories whenever there are matching values in a common field. It return an array of property property from result of inventories joint.	See innerJoin.

Note

First argument of a filter is always on left of pipe: arg1 | filterName(arg2, arg3, ...).

innerJoin

This filter return an array of property property resulting from the combination of an entry in another inventory. Combination is base on match of property foreignKey on both table.

Warning

Property foreignKey has to be exactly named the same in both inventory.

The following figure show the usage of filter and result given:

This example show usage the filter in a concrete case.

Including inventory

To import an Inventory, target properties fileRenderContext inject content inside the context based on the key name. A simple example :

"fileRenderContext": {
  "deviceModbus" : "template/inventory/modbus.csv"
}

Will be available as deviceModbus inside the .nunjunks file.

{% for entry in deviceModbus %}
    {{ entry["devices"] }}
{% endfor %}

Variable evaluation order

Nunjucks engine

Capability	Support	Comment
Access loop element directly from an array		See the official documentation
Using dash in variables name		See the official documentation for detail

This kind of target use a template engine that allow user to script the generation of a file. This target gather a context that variable and datas that will finally be exposed during Nunjucks template resolution.