Templates: Instantiating and Updating
The operations in order — release, instantiate, update, link, delink — and what to verify after each.
This article covers the template operations themselves. Read Templates: Concepts first if the class-and-instance model is not yet familiar.
The operations#
| Operation | What it does |
|---|---|
| Create Template | Turn existing content into a template definition |
| Release | Publish the template so it can be instantiated |
| Instantiate | Create new model entities from the template |
| Update | Push template changes into existing instances |
| Link | Attach existing local content to a template |
| Delink | Detach an instance, making it ordinary local content |
| Derive | Create a local template from a remote one on a template server |
Preparing to instantiate#
Four things need to be true before you instantiate anything.
- The template is authored in the Template view, complete and correct.
- The template is released. An unreleased template creates nothing, without an error.
- The destination folders exist, one per instance.
- The model attributes are set on those destination folders, with values formatted exactly as the source systems expect —
010, not10.
Getting the attributes right first matters, because an instance created against a missing or mistyped attribute looks perfectly normal and reads the wrong tag.
Instantiating#
Instantiation creates a full copy of the template's content, linked back to it, in a destination folder.
You supply a name pattern for the created entities. Patterns can incorporate a sequence number and attribute values, so instantiating three times can produce Unit 1, Unit 2, Unit 3 with matching attribute values, in one operation. Sequence numbering is 1-based.
Remember that measures do not participate in attribute-driven naming — their names come through as authored on the template. The instance identity comes from the containing metric and folder.
Instantiate one, verify, then do the rest. Create a single instance and check it end to end — the tag resolves, the calculation produces a sensible number, the limits and charts arrived — before instantiating the other nineteen. An error in the template or an attribute is trivial to fix once and tedious to fix twenty times.
The Bulk Instantiation form#
In Flow Config, instantiation is drag and drop: drag a template folder or template metric from the Template view onto the folder in the Model view that should become its parent. Drop it on the root and the instance is created at the root.
The drop opens the Bulk Instantiation Configuration form, where the instantiation count and the naming are set. That is what makes "create twenty instances" one operation rather than twenty.
Release the template first, or the drop will not do what you expect. An unreleased template carries a grey disc in the Template view. Right-click it and choose Release before instantiating. This is the most common reason an instantiation appears to do nothing at all — see Templates: Concepts.
Where the template locks properties, the resulting instances cannot edit those fields. Each lock is shown on the instance's form next to the property it protects — including, on a measure's calendar tab, the Time Slice Aggregation lock that governs how an event-sliced measure aggregates its slices — and a template update overwrites a property on an instance only when the template locks it. An unlocked property keeps whatever the instance set.
After instantiating, the created entities are ordinary model content that happen to be linked to a template. They still need deploying before they collect anything.
Verifying an instance#
Work through this the first time, for each new template:
- Structure — every expected metric and measure is present, and nothing is duplicated.
- Tags — the resolved tag exists on the connection. Browse the namespace rather than assuming.
- Intervals and aggregations — the chain is intact and Counter appears exactly once on any totaliser.
- Calculations — expressions compiled, dependencies resolved to this instance's measures.
- Attributes — resolving to the values you intended at this point in the tree.
- Limits and charts — present and bound to this instance's measures.
- Values, after deploying — the numbers are plausible for this piece of equipment.
Step 4 deserves attention. A calculation's dependencies should point at the instance's own measures. If two instances' calculations both reference the same measure, something has gone wrong and every instance will report the same numbers.
Updating instances#
When you improve a template — a better formula, an extra measure, a corrected unit — an update pushes that change into the instances.
The sequence:
- Edit the template.
- Release it again, so the new definition is published.
- Update the instances.
Updating compares each instance's recorded template version against the template's current version. Instances already current are skipped, so an update is cheap to re-run and harmless to repeat.
Templated members are overwritten; local additions are not. An update overwrites the members an instance got from the template. Any local edit to those members is lost. Content you added locally to an instance — a measure the template does not have — is untouched.
If a per-instance difference needs to survive updates, it must be either a model attribute (a value that differs) or a local addition (content the template does not own). Editing a templated member and hoping is not a strategy.
Scope your updates deliberately#
You can update everything, or a subtree, or a single instance.
Narrow scope is safer and quicker to verify. A staged rollout — one instance, check, then one area, check, then the rest — is the right approach for a template with many instances, particularly if the change affects calculations that feed reports.
Verify a partial update landed where you expected. When updating a subset of instances, check afterwards that the instances you intended were updated, that they show the new template version, and that instances outside the scope are still linked to their templates. Confirming the outcome is quick and turns an assumption into a fact.
Linking existing content#
Link attaches content that already exists locally to a template, making it an instance without rebuilding it.
This is how you retrofit templating onto a model that grew by hand. It works best when the existing content genuinely matches the template's shape and naming, because matching is done by name within the container. Content that differs will need aligning first.
Realistically, retrofitting is worth it when there are many similar instances to bring under control, and not worth it for two or three.
Delinking#
Delink removes the template relationship and leaves the content in place as ordinary local entities. It cascades to child measures.
Use it when equipment has genuinely diverged and will be maintained independently from now on. Understand that it is not easily reversible and that future template improvements will never reach that content.
Delinking is not the answer to "this update did something I did not want". Fix the template and update again.
Doing it from the CLI#
All of this is scriptable, which is how large fleets are built repeatably:
# release first — instantiation of an unreleased template creates nothing
"Flow Config.exe" ... --release --entity-type metric --entity-id <id>
# instantiate three units with a name pattern and matching attributes
"Flow Config.exe" ... --instantiate --source-entity-type metric --source-entity-id <id> \
--destination-entity-id <destination> --name "Unit {0}" --instance-count 3
{0} is the 1-based sequence number, usable in both the name pattern and attribute value patterns.
Assert the result rather than trusting the exit code. After a scripted instantiation, list the created entities and confirm the count is what you asked for. An instantiation that produces zero entities — the unreleased-template case — is the failure mode most worth guarding against in a build script, because everything downstream then quietly builds nothing.
Diagnosing template problems#
| Symptom | Usual cause |
|---|---|
| Instantiation created nothing | Template not released |
| Instances all read the same tag | Attribute token missing from the tag, or attribute set too high in the tree |
| Some instances have a wrong tag | Attribute value formatted differently — leading zeros, case, spaces |
| A local edit disappeared | It was on a templated member; an update overwrote it |
| Update did nothing | Instances already at the template's current version, or template not re-released |
| Duplicate entities appeared, some named as copies | Ambiguous matching — two candidates with the same name in one container |
| Instances no longer receive updates | They were delinked |
| A calculation references another instance's measure | Template authored with a hard-coded dependency instead of a relative one |
Practical habits#
Keep templates in a clearly named place. A <Area> Templates folder in the Template view makes ownership obvious.
Change templates in maintenance windows when instances feed live reports, because an update recalculates values.
Record what you released and when. When numbers change shape, the first question is what changed, and template releases are a common answer.
Never edit a templated member on an instance. Make it an attribute, make it a local addition, or change the template. Those are the three legitimate options.