Configuration template

Capabilities

Capability	Support	Comment
Single file template		Template a single file (see simple Inheritance)
Single file template - variables overriding
Single file template - Sharing variables between multiples files		A file or template can import one or more variables.ospp that contains variable that can be used by the templating. See variable file
Single file template - template of template
Single file template - multiples files Inheritance (many templates used by one file)		To avoid configuration error and conflict this feature will not be supported
Template playbook - Complexe template on multiples files		See templating playbook

Examples

• Value template example Simple template variable usage

• Template for variables files example Usage of variables files

• Template for an hysteresis use case Usage of a template to create an hysteresis

Concepts

Templates provide a way to simplify the integration process when a lot of files share a common structure and only a few elements must be changed for each individual item.

They allow individual files to define only a subset of required fields and rely on a more generic template file (or template file chain) to provide other configuration fields. They also allow variables to be defined in templates, with their actual value defined in the individual files referring to the template.

Single file Template (Inheritance)

Usage

Almost any OnSphere configuration file can be templated by defining a file of the same name with the .template extension (for example value.ospp.template), and referencing it.

To reference a template the templateId field is used. As the ItemId can be used for multiple template (Value, Owner, …), when the resolution is done the ItemId will point to the template file with the same name as the original file (value.ospp -> value.ospp.template).

Evaluation rules

Templates can themselves be templated. In that case, the templates must all have the same name (with the extension .template only once, not one per level), and are evaluated from bottom (the file referencing the first template) to top (the template that references no other template). Fields are inherited from top to bottom and are overridden from bottom to top.

Variables

All variables defined in a user of a template override the variables inherited from a template (i.e., they replace the field if it was inherited, or they define it if it was not).

Note

Variables can be used freely for defining references (moduleId, templateId, accessedValues, …).

Overriding

All fields defined in a user of a template override the fields inherited from a template (i.e., they replace the field if it was inherited, or they define it if it was not).

Objects :

Only the fields that are explicitly defined in a user of a template will be overridden, even if they are inner fields of a more complex object. It means that an object must be completely redefined for it to completely override the object inherited from the template.

Arrays :

When overriding the content of an array, new elements are simply added to the array. It means that elements in an array cannot be overridden or removed.

Here is an example :

root/value/callback.ospp

{
    "templateId": "root.template",
    "linkedOutputs": ["root.other-output"]
}

root/template/callback.ospp.template

{
    "linkedOutputs": ["root.output"]
}

The result will be interpreted as if the value.ospp file was defined as :

root/value/callback.ospp

{
    "linkedOutputs": ["root.output", "root.other-output"]
}

Variables files

Variable can be used locally or in a an external file named variables.ospp referenced by variablesFiles entry in any json files. They behave like the other variables when inherited. When multiple variables file are present, the variables contains inside the first variableFile of the list take precedence over the one declared below it.

Note

A variable is defined within the file that incorporates the variablesFiles, and within the variablesFiles, the corresponding value will be sourced from the file who incorporates.

Examples

• See Simple template variable usage

• See Usage of variables files

Illustration

Here is an example of a template file that defines a variable name, description and type for a value. The value.ospp file simply references the template and provides the variable content.

• Red color show a static link for templateId

• Green color show a dynamic link templateId defined by a variable

Static reference

Red elements show a static link to a template

Dynamic reference

Green elements defined a link configured by a variable defined in the initial value.ospp.

Overriding variables

In orange in the example, we use the internal variables to define the unit of the smooth:

1. The default variable is defined with the value DAYS in root.modbus.template.

2. The variable is redefine in value.ospp with value MINUTES.

3. As value.ospp is the most specific file, the value will be set to MINUTES.

In blue in the example, we use the external variables to define the value of the smooth :

1. The default variables is defined with the value 20 in root.modbus.template.default.

2. The variable is redefine in root.basement with 5.

3. As variables.ospp is the most specific file, the value will be set to 5.