Model Attributes

The idea#

Suppose twelve production lines each need the same eight measures, but each line has a different design capacity and a different unit number embedded in its tag names.

Without attributes you build twelve near-identical copies and edit the differences by hand. With attributes you build one template that reads Design Capacity and Unit Number from wherever it happens to be instantiated, then set those two attributes on each line folder.

Production
+-- Line 01          Unit Number = 01,  Design Capacity = 12000
|   +-- (instance of the line template)
+-- Line 02          Unit Number = 02,  Design Capacity = 12000
+-- Line 03          Unit Number = 03,  Design Capacity = 18000

One template, three attribute pairs, three fully configured lines.

Inheritance#

An attribute set on a folder is visible to every folder, metric, and measure beneath it. Set the same attribute name lower down and the lower value wins for that subtree.

Riverside Plant       Site Code = RVS
+-- Production        Cost Centre = 4100
    +-- Line 01       Unit Number = 01
    |   +-- Filler    > sees Site Code=RVS, Cost Centre=4100, Unit Number=01
    +-- Line 02       Unit Number = 02, Cost Centre = 4200
        +-- Filler    > sees Site Code=RVS, Cost Centre=4200, Unit Number=02

This is why folder structure and attribute design are the same exercise. Attributes only reach the right things if the tree puts those things underneath the right folder. See The Model Tree.

Where attributes are used#

In tag addresses. A retrieved measure's tag can include an attribute token, so one template resolves to a different tag per instance:

[ModelAttribute("Unit Number")]-FT-001.PV

In queries. SQL-based connectors accept the same token in a query, alongside period tokens:

SELECT Value, Quality FROM Readings
WHERE UnitNo = '[ModelAttribute("Unit Number")]'
  AND Stamp > [PeriodStart] AND Stamp <= [PeriodEnd]

In calculations. Expressions read attributes through the context. Values are strings, so convert:

Convert.ToDouble(Context.ModelAttributes["Design Capacity"].Value)

Guard the conversion where the attribute may be missing or blank — a helper function is worth having:

AttrAsDouble(Measure_1043.ModelAttributes, "Design Capacity", 0)

In instance names. When instantiating a template, attribute values can drive the names of the created entities, so instances come out named Line 01 Filler rather than needing renaming afterwards.

Attribute values are strings#

Every attribute value is text, regardless of what it represents. A capacity of 12000 is the string "12000".

Consequences to design around:

• Convert explicitly in expressions, and handle failure.
• Be consistent about formatting. 01 and 1 are different strings. If an attribute is used in a tag address, its exact form matters — a leading zero that some instances have and others do not will produce tags that do not exist.
• Decide about blanks. A missing attribute and an empty one behave differently in expressions; pick a convention and guard for it.

Designing an attribute set#

Name for meaning, not for use. Design Capacity is better than Divisor, because in two years someone will need to know what the number means.

Keep the set small. Five or six attributes per template is comfortable. Twenty means the template is trying to be configurable about things that should be separate templates.

Set them at the right level. A site code belongs on the site folder. A unit number belongs on the equipment folder. Setting a site code on every machine works and is a maintenance liability.

Prefer stable facts over volatile ones. Design capacity, unit number, and cost centre change rarely. A monthly target changes constantly and belongs in a manual entry measure, where it is versioned by period and can be entered by the people who own it.

That last distinction is the one most worth getting right. An attribute has one current value with no history; a manual entry measure has a value per period. If you need to know what the target was last March, it was never an attribute.

Attributes and templates together#

The usual workflow:

1. Design the attribute set — what genuinely differs between instances.
2. Author the template referring to those attributes in tags, queries, calculations, and names.
3. Set the attributes on each destination folder.
4. Instantiate the template into each folder.
5. Verify one instance end to end before doing the rest.

Step 5 matters. An attribute typo produces an instance that looks correct and silently reads the wrong tag or divides by the wrong capacity.

Diagnosing attribute problems#

The quickest diagnostic is to compare two instances — one working, one not — attribute by attribute. The difference is almost always a string that does not look like what you assumed.

A worked example#

Twelve lines, tags of the form <unit>-FT-001.PV, each with a design capacity, reporting efficiency against capacity.

Attributes on each line folder: Unit Number (010, 020, …) and Design Capacity (12000).

Template metric Throughput:

Instantiate into all twelve line folders. Each resolves its own tag and its own capacity, and a later improvement to the template — a better utilisation formula, an extra measure — propagates to all twelve with one update.

See also#

• Templates: Concepts
• Templates: Instantiating and Updating
• Calculation Expression Reference
• The Model Tree