IOTA Stage

The IOTA staging area: a database that IOTA Vue reads directly.

A tag sync writes time-series tags here — one Stage tag per PI
point — and each one either holds its values or references them. Assets and attributes
are a different pattern's job.

Fields

Field	Notes
Host	The Stage server, e.g. https://stage.example.com
Database	The Stage database to write into
Create the database if it is missing	Off by default; see below
Authentication	Basic, Bearer token, or OAuth client credentials

The authentication method decides which fields appear under it, so only the ones that
apply to your choice are shown:

Method	Fields
Basic	Username, Password
Bearer token	Bearer token
OAuth client credentials	Tenant Id, Client Id, Client Secret, Scope

Creating the database

With Create the database if it is missing turned on, Test connection will create
the database named above if the host does not have it: created when absent, used as-is
when present, never altered and never dropped. Off, a missing database is reported and
the run fails.

It is off by default, because creating a database on a host is not something to do
because a name was mistyped.

Test creates it rather than promising to

Most connection tests answer a question and change nothing. This one acts, and
deliberately: a test that only promised to create the database could not prove the
credential is allowed to, so the test would pass and the run would fail on permissions
at two in the morning. Creating is idempotent, and a name already taken is read as
success, because the name existing is all the caller wanted.

Stored or Reference

A Stage destination is the only one that asks how the tag should get its values, and
the choice is made once per pattern, on General beside the destination endpoint.

Mode	The Stage tag	Values arrive
Stored	holds its own series	a tag sync task copies them in
Reference	holds nothing	Stage reads the source itself, through its AF Driver

Stored behaves like every other destination. Verify and Manual Backfill work on it
exactly as they do for PI, CDS and CDF, and a scheduled task keeps it current.

Reference has no task at all. There is nothing to copy and nothing to back-fill, so
Stream refuses a data task on one and both buttons say why. In exchange there is no
second copy of the data and nothing to keep in step.

Reference needs a source Stage can reach

Reference mode is only offered where the pattern's source endpoint has a
request topic — the AF Driver that issues the FQNs and that Stage reads through. A
source read in process has none, and saving is refused with the endpoint named:

a stage destination in reference mode needs a source reached over NATS: endpoint
[…] is read in process (no reqtopic). Set its reqtopic to the AF Driver that serves
[…], or use mode "stored".

There is no separate "which driver" field here: the source endpoint's request topic
is that choice. Stored mode accepts any AF/PI source, local or remote.

What a tag sync writes here

A Stage tag is keyed by its id, and the default is [tag.pathhash] — a 32-character
hash of the PI server's unique id and the tag's name.

Why a hash	Each half is the durable one of its pair. A server's unique id survives a rename where its name does not; a tag's name survives being deleted and re-created on PI, where its point id does not — and point ids repeat across servers
Why it matters here more than elsewhere	Stage never reuses an id. A retired one is spent for ever, so a key that moves cannot be recovered by deleting and re-creating the tag

Six properties are mapped: id, name, UOM, instrument tag, source and
labels. assetId is offered and left blank — set it to the Stage element the tag
belongs to, which must already exist in the database.

Labels are compared as a set, so order and spacing are not drift. The default writes
two, pointsource=… and pointtype=….

The rest are derived by the service and shown greyed:

Derived	From
Value type	the source type — Float16/32/64 → float, Int16/32 → int, anything else → string
Minimum / Maximum value	a numeric source's bounds. A string, digital, timestamp or blob source gets no range
Database	the endpoint's own
Is reference	the mode above
FQN	reference mode only: the source tag's name as its AF Driver issues it

A digital point becomes a string tag at Stage carrying its state names, which is why
it gets no range — its state codes would mean nothing there.

When a tag cannot be made to match

Stage is stricter than the other destinations about what can be changed after the fact,
and a tag sync reports the result as Mismatch rather than drift. A
run will not clear one:

The note says	What it means
the Stage tag was retired	the id is spent for ever — change the key template
the Stage tag is a reference tag, this pattern's mode is stored	a tag's kind cannot change in Stage
the Stage tag holds its own values, this pattern's mode is reference	the same, the other way round
the Stage tag references […]	a reference cannot be re-pointed

Each has the same two ways out: match the pattern to the tag that is there — usually by
switching the mode — or change the key template so the sync addresses a different
tag. Deleting the Stage tag is not a third way, because the id it used cannot come back.

Two patterns over one tag will collide

[tag.pathhash] is derived from the server and the tag name, so every pattern over
the same PI point produces the same Stage id. Point two patterns at one tag and the
second reports a mismatch it cannot clear — most visibly when they disagree about the
mode.

If you want two Stage tags for one point, give one of the patterns a key of its own —
stored_[tag.pathhash], say.

Writing values

A fill into a stored Stage tag writes only what is missing. Stage appends and never
overwrites, so a value it already holds that disagrees with the source is reported under
Different and never sent — there is no write mode to choose.

A write can also be refused for being too old: Stage keeps an out-of-order limit of
about 24.8 days behind a tag's newest value.

A verify compares value and quality, since Stage keeps the good/bad flag.

Related

• Endpoints: the list, and how a connection is tested
• Tag Sync: the pattern that creates and maintains these tags
• Tag Sync Task: what moves the values into a stored tag