Instantiating template entities refers to the process of creating linked model entities.
When instantiating a template entity, one is creating a model entity that is a copy (or, "instance") of the template. One may instantiate multiple instances of a template entity.
Each instance will be configured with the same configuration and property values as its template, and where properties are locked, one will not be able to make changes to the instantiated entity.
Instantiation is a drag + drop process. To instantiate a template, drag the Template Folder or Template Metric that you wish to instantiate from the Templates tree to the Model tree and drop it onto the Model Folder that you want to become the parent.
Make sure your template is "Released", else this operation will start the instantiation process.
A template can be released by performing a "right click" operation on the components in the template view and selecting the "Release" option. Notice an un-released template will have a grey disk icon, indicating that it is not ready to be instantiated.
If you drop the template onto the root level of the Model tree, then the Template Folder or Template Metric will be instantiated at the root level.
One must drag the template entity that requires instantiation from the Templates tab to the Model tab. Upon dropping the template entity in the Model tab, one will be presented with the "Bulk Instantiation Configuration" Form:
- Instantiation Count - the number of instances that will be created by the instantiation operation
- Source Template - The template this will be instantiated
- Model Destination - Where in the model the template will be populated
- Template Map Setting - Any placeholders configured in the template will be populated to be replaced by the instantiation process.
What will be available to be replaced in the Template Map Settings?
Model attributes used as place holders in the templates as well as generic placeholders will be listed to be replaced by the instantiation process.
These can be used in the following places:
- Folders - Instantiated Name Property
- Metrics - Instantiated Name Property
- Measures - Tag Retrieval Property
See in the example below, the Steam Metric has a Model attribute linked in the Instantiated Name Property of the metric:
Placeholders must be placed inside square bracket . Model attributes can be "dragged" from the attributes section in the toolbox view to auto populate them. The syntax for model attribute is: [ModelAttribute("Boiler Number")]
Generic Placeholders can also be used. These will only be replaced once and will not be available after the process to be changed/modified.
These must also be placed in square brackets.
See in the example below, the Steam Folder has a Generic Placeholder, [X] to in the Instantiated Name Property:
The "Bulk Instantiation Configuration" Form will now present you to replace both placeholders, the model attribute as well as the generic placeholder:
The Values and Format options can the be specified.
- Values - what should the placeholders be replaced with? this can either be:
- Static once of value i.e 010
- CSV list of Values i.e 010,020,030,040
- Range of Values i.e. 10-40/10 (First portion of the syntax is to specify the range, so in this example it will populate values from 10 to 40. The second portion is how bog the steps should be, so /10 means in steps of 10. So the example will generate values 10,20,30 and 40)
- Please be aware of your instantiation count when specifying the values
- Format - formatting can be applied to the values populated, i.e. padding values by a zero, one can specify a format of "000"
See an example below. We are instantiating 10 boilers, replacing the Boiler Number attribute using values 10-100/10 and replacing the generic placeholder with 1-10/1:
The "Mapped Preview" will show how the placeholders will be replaced, in this example, folder names are replaced by the values for placeholder [X] and metric names are replaced by the "Boiler Number" model attribute values. This will be populated by pressing the "Preview" button in the top right corner.
The second example will yield the same result, but instead of a range, a CSV list is supplied for the "Boiler Number" attribute:
If there is potential mismatch between the value ranges and the instantiation count, the preview window will highlight this. In the example below, the values are specified to have 10 replacements, but the instantiation count is set to 12. Thus 2 additional instances will be created as "copies".
If the results in the preview window yielded the correct replacement values, one can press the "Continue" button in the top right corner to start the instantiation process.