Reusable tag models

Open Models in the workspace's left navigation to build reusable models and add equipment. A model is a recipe for the values a machine needs; each piece of equipment uses that recipe with its own source data. Technical details and exported files call these types and instances. Models is separate from Tags, which manages individual values, and from Gateway Settings.

Models shows a Plant | Models explorer beside a detail page. Create a model from connected data, a template or a blank start with ＋ New, add machines and place them in locations on the Plant side. ⋯ → Data update settings manages shared scan intervals and the built-in [default] provider. Every page shares one draft; the draft bar at the bottom offers Review & apply. Gateway Configuration capability or administrator access is required. The review reports affected tags, retained overrides, parameter provenance and dependency conflicts. A conflict blocks Apply; a concurrent configuration or connection edit requires another review. Runtime memory writes use a separate checkpoint and do not change the configuration revision. Follow the UNS model setup walkthrough, including the simple three-press exercise, for a complete example.

Define, instantiate and upgrade

1. Choose New model and give it an ID. A new model starts at version 1; versions can range through 1,000,000. Drag tags or folders from Choose data to add fields that read their existing values. Fields can also use memory, expressions, OPC UA or saved source points; nesting another model pins its version. Field paths are relative (Count, Metrics/Rate). Inputs or reference targets beginning ./ address fields of the containing model; concrete paths can refer outside it.
2. Add parameters when the model needs a value that differs for each machine, such as Device. Keep the model in the draft while adding equipment; there is no need to apply it first. Saved model versions are immutable. Select one and choose Edit a new version to make a new revision.
3. In Add equipment, add a machine at a concrete [default] path, supply its parameters and enter overrides only when needed. An override changes one field for one machine. In exported JSON, {"Count":{"value":12}} overrides one initial value; Spindle/Speed addresses a nested field. Equipment paths cannot overlap each other or direct tags.
4. Review and apply the model and equipment together. To adopt a later model version, open that version, select the intended equipment and use Bulk actions → Update selected to vN. Review displays expanded field changes and retained overrides. Unselected equipment keeps its old version. Bulk actions → Paste spreadsheet rows accepts path,definitionId,version,<parameter names> for up to 2,000 instances. Blank parameter cells use the model default or omit the value. A batch is reviewed and applied atomically.
5. Remove an override field to inherit the definition again. Authored instance overrides are retained by an upgrade. Runtime memory writes instead persist in tag-values.json, keyed to the exact expanded definition; a changed definition invalidates that checkpoint and uses its authored default or override. Do not rely on an upgrade preserving a runtime counter. Source kind and data type belong to the definition. An incompatible authored override value or an override targeting a removed member blocks the upgrade until corrected.

Generated members are visible in the ordinary tag browser with their definition, version, full model path and overrides. Edit them through the instance/model workflow. Removing an instance or definition also uses preview; a referenced definition, scan group, expression input or reference target cannot be removed while still required. Browser component tag bindings are outside gateway dependency validation. Designer Model diagnostics report missing members in typed indirect bindings; existing layouts are not regenerated after upgrades.

Parameters, references and hierarchy

Types may declare up to 32 String, Double, Int64 or Boolean parameters, with optional defaults and required flags. Complete {name} placeholders are substituted once in source fields (connectionId, nodeId, target, expression input paths), whole memory values and nested type arguments. Member paths, kinds and data types remain fixed. An explicit member override takes precedence over the parameter-substituted definition, then the parameter default. Resolved fields must pass the same validation as directly authored values.

A reference mirrors an existing tag's value, quality and timestamps with an exactly matching data type. It creates no acquisition or subscription, but counts as one tag and is read-only. Scaling requires an expression. Reference and expression chains share cycle detection and a maximum dependency depth of 64. Type composition is pinned to explicit versions, limited to four levels and rejects cycles. Inside a nested type, ./ refers to that type's own members.

Reading a reference requires read permission on its alias/member path; it does not also require permission on the target source path. A curated model can intentionally expose selected raw values to operators who cannot browse the raw namespace. Configuration administrators must review that exposure before applying. Reference targets after apply in Model and tag-import reviews lists every resulting alias and resolved target, including parameter substitutions, overrides and unchanged references. Restricting the raw source path does not revoke access through an allowed alias.

Members can carry units, descriptions, numeric ranges, enum constraints, freshness rules, semantic identifiers and scalar attributes. Units do not convert values. Ranges never clamp values, but range, enum and freshness violations affect modeled quality while retaining the source value and quality. Model alarm templates feed the existing alarm engine. See model operations. Organize → Add location declares optional ISA-95 hierarchy nodes without creating tags. In Settings, the provider option Require instances under declared hierarchy validates all instances against declared ancestors before applying. Hierarchy levels are Enterprise, Site, Area, Line, Cell, WorkCenter and Custom.

The Designer tag browser and binding picker provide Raw tags and Model tabs. The Model tab is an expandable tree of locations, folders, machines and their fields, with a refresh icon at the top. Selecting a field inserts its ordinary concrete tag path. A template Model instance parameter declares a required type ID and optional inclusive version bounds; its value is a concrete instance path. Bind with {machine}/Spindle/Speed. Create faceplate, shown under an expanded machine, generates an editable value component per leaf, showing unit and quality, for an instance with 1–500 leaves. It requires access to every member and rejects larger instances rather than exceeding the existing 500-component template limit or omitting values. It is a starter, not a maintained generated artifact.

Model requirements filter the picker and produce Designer diagnostics; they are not a runtime type or version gate. Manually entered or dynamically supplied paths are syntax-checked and use ordinary tag bindings with existing read permissions. Check Project diagnostics → Model requirements before publishing, especially after selective instance upgrades.

Scan groups and provider lifecycle

A named scan group has an enabled flag and an interval from 100 through 60,000 ms. Choose its name on an ordinary tag or use the scanGroup member field. Group timing overrides individual timing. OPC UA subscriptions request that interval; expression evaluation uses the gateway’s 100 ms scheduler resolution. Memory tags retain their values and original source timestamps rather than generating periodic data samples.

OPC subscriptions group compatible connection, interval, deadband and queue settings, then partition each group into at most 1,000 distinct nodes per watch. Multiple tags referencing one node stay together. The gateway still permits at most 32 active watches; many different settings can exhaust that allowance before reaching 10,000 tags. Provider diagnostics report rejected watch groups rather than silently omitting their values.

Disabling a group, instance, or tag produces Bad_Disabled quality for its affected tags. Models → Settings shows configured/good/unavailable/disabled counts and running/degraded/disabled state. Disabling [default] disables its configured and sample tags, rejects memory writes, and stops configured OPC subscriptions. Re-enabling restarts acquisition. Connection enable/disable remains independent. Provider health is a snapshot refreshed on opening the workspace or applying a change.

Types, quality and timestamps flow through the existing engine: expression values have their declared scalar type, bad input quality propagates, and derived timestamps use the newest contributing source timestamp. OPC values preserve their device/source timestamp; references preserve the target's timestamps and retain its quality as source quality before applying their own field rules. Alarm templates are included in the model. Additional providers, inheritance and historian defaults remain outside this format. MQTT model publishing is configured separately; an i3X server and DIME hand-off remain deferred.

Model API leaves report the effective tag timestamp, optional sourceTimestamp, and optional gateway-ingestion receiptTimestamp. Receipt time is not the model request time or a universal device-server timestamp; unavailable metadata is null. There is no serverTimestamp alias.

Import/export and storage

Export model and Export configured tags download the same complete sparkstudio.tags package. The file contains tags, udtDefinitions, instances, scanGroups, hierarchy and the default provider. Imports merge by tag path, definition ID/version, instance path, scan-group name and hierarchy path. Resources absent from a file are retained. Arrays may be empty. Omitting provider preserves its current state. There is one current schema, identified internally by version: 3, with no alternate export format.

Explicit removal arrays are removeTags, removeInstances, removeScanGroups, removeHierarchy and removeUdtDefinitions; the last uses keys such as Counter@1. The same resource cannot be imported and removed in one transaction. Unknown fields, additional providers, duplicate identities and unsupported definitions are rejected. Connections and saved points are configured separately and must exist for source members. Configuration limits are 10,000 expanded tags across the gateway, 256 definition versions, 2,000 instances, 2,048 hierarchy nodes, 128 members per definition and 32 scan groups. Direct tags, references and expanded members share the tag allowance, including disabled definitions. Historian recording and alarm definitions have separate limits; this configuration ceiling does not promise a particular update rate.

Storage and import accept only the current tag schema. Older envelopes, flat tag arrays and unknown formats are rejected without rewriting them; there is no automatic tag migration. Preview remains read-only. Restore backups with their matching gateway build, and keep the original data directory rather than lowering a format marker manually. See gateway recovery.

Exports include configured memory defaults and authored instance overrides. .sparkproj exports exclude gateway tag resources, but preserve template Model instance requirements. Import on a gateway without a required type succeeds and produces unresolved Designer diagnostics; keep gateway setup instructions with the project. Scoped /model/types, /model/tree, /model/instances and /model/object reads use existing tag-read permissions and omit inaccessible member values.

Workshop: one definition, two units

The independently authored examples/unit-model-workshop.json fixture and tools/load-unit-model-example.mjs loader use synthetic memory and expression values only. This is a gateway-setup-required workshop, not a self-contained project package. Use the fixture and loader from the same source build as the gateway. Prerequisites: a disposable local SparkStudio gateway, an administrator account and the enabled default provider. No equipment connection or device command is used.

From the source checkout, set SPARKSTUDIO_ADMIN_AUTH_FILE to a protected local JSON credential file, then run:

node tools/load-unit-model-example.mjs http://127.0.0.1:5091

The loader creates WorkshopCounter@1, WorkshopRefresh, West/East instances and a draft project. It refuses reserved-name collisions. Publish the project explicitly in Designer, or add --publish when deliberately requesting publication. West displays 50% (8/16); East displays 75% (9/12).

Create definition version 2 from version 1 and change the Completed default to 10. Upgrade West only. Its Goal override remains 16 and its progress becomes 62.5%; East stays pinned to version 1 at 75%. Disable/re-enable WorkshopRefresh: both expression tags become unavailable/recover while the stored counts remain intact. Try removing Goal from a new version and upgrading West: its retained Goal override creates a conflict, and apply remains unavailable. Export the tag model, preview it again and inspect its pinned versions and overrides. Project package import remains unpublished until explicitly published; re-export preserves its screens while gateway setup remains separate.

Run node tools/test-tag-model.mjs for temporary-fixture validation of format handling, type-version pinning, atomic conflicts, runtime quality/timestamps, restart, and workshop project export/import/publication/re-export. No live gateway is contacted.