Atlas API - Subscribing to Live Values

Overview#

Live values leave Atlas through the value hub, a SignalR hub. This is the supported way to receive values as they change, and it is how Bridge and Explorer read from Atlas.

Two things are worth stating before anything else:

• It is a streaming API, not a callback API. Every subscription method returns a stream. You call StreamAsync and iterate. You do not register a handler with connection.On(...), and if you try, nothing will ever arrive.
• The same hub also serves history. Four GetRange* methods return stored ranges over the same connection, so you do not need a separate REST call to backfill a chart before going live.
• It also describes a type's shape. SubscribeToTypeDescription streams a type's columns, endpoints or enum roster, so you can learn what a rowset will contain before you subscribe to any value.

This article covers connecting, the nine methods, what you receive, and the traps.

Connect#

The branch and domain are pinned by the URL, not passed as arguments. One connection serves exactly one world:

/hubs/v1/branches/{branch}/domains/{domain}/subscribe

So a client following two domains opens two connections.

Authentication#

The hub accepts either a session cookie or a bearer token, under the HubAccess policy. A machine client attaches the bearer through SignalR's access-token provider rather than a header, because the WebSocket handshake does not carry your custom headers:

var connection = new HubConnectionBuilder()
    .WithUrl("https://atlas.example.com:4552/hubs/v1/branches/main/domains/PlantModel/subscribe",
        options => options.AccessTokenProvider = async () => await tokenProvider.GetTokenAsync())
    .AddMessagePackProtocol()
    .Build();

await connection.StartAsync();

Two rules that cause most failed handshakes:

• A failed handshake returns a plain 401, never a redirect. Atlas overrides the cookie handler's redirect-to-login for exactly this reason: a negotiate or WebSocket handshake cannot follow a 302. If you get HTML back, you are talking to the wrong plane.
• The audience rule applies. The calling client's Pulse registration must list Atlas's Pulse:Auth:ClientId (default Atlas) among its audiences, or the token is rejected even though it is valid. See Registering Timebase apps as OAuth clients in Pulse.

Protocol#

Atlas registers the MessagePack protocol on its hubs, and the value payloads are designed for it: the DTO uses positional [Key(n)] members, and Guid values ride the wire as a 16-byte binary through MessagePack's native GUID resolver rather than as a 36-character string.

Use .AddMessagePackProtocol() in a .NET client, as above. Atlas does not raise its receive-message size limit against you, so large rowsets are not truncated.

On non-.NET clients: the shipped clients are .NET and use MessagePack. If you are connecting from JavaScript or Python, expect to do protocol work, and note that the [Key(n)] layout means the MessagePack form is a positional array rather than a named map.

The four value subscription methods#

These are the value half of the hub. The fifth method, which describes a type rather than streaming its values, is covered in Describing a type before you subscribe.

Which one you call determines what you are following. These map one-to-one onto Bridge's SubscriptionMode, so if you have configured Bridge, the shapes will be familiar.

Every one of them yields an initial rowset carrying the current value first, then one rowset per change. You do not need a separate priming read to populate a display.

Streaming, not callbacks#

await foreach (var rowSet in connection.StreamAsync<ValueRowSetDto>(
    "SubscribeToInstance",
    "urn:demo:F-101",
    true,            // emitFullRow
    false,           // includeWatermarks
    cancellationToken))
{
    Render(rowSet);
}

Cancelling the token ends the subscription. There is no explicit unsubscribe call: you stop by cancelling or by disposing the connection.

emitFullRow#

• true sends every property on each change. Simplest to consume, more bytes.
• false switches the stream to its delta variant, where only the changed columns carry a value. The rowset's Present mask says which columns those are: an entry of false means the emit carries nothing for that column, and its cell is shipped as null so that a consumer which ignores the mask still reads a null rather than a stale value.

A null cell is a null in both variants. It never means "unchanged": a column that changed to null in delta mode is Present[c] = true with the cell's null bit set, which is how you tell it from an unchanged column. Choose true unless volume is a real problem. Delta mode is where a consumer that reads nulls without the mask overwrites good stored values, which is the case Bridge's SQL plugins cover by honouring the mask.

includeWatermarks#

When true, rowsets carry a populated Watermarks array, and watermark-only advances arrive as null-cell rowsets. That last part matters: with watermarks on, you will receive rowsets that contain no values at all. They are progress signals, not data, and a consumer that assumes every rowset carries a value will misread them.

What you receive#

ValueRowSetDto has six members:

A compound-ranged property yields a multi-column rowset, one column per leaf, rather than a single value. So subscribing to a TVQ-ranged property gives you timestamp, value and quality as separate columns in one row. Subscribing to a compound parent URI does the same thing one level up.

A column's wire type is the column's declared xsd type, as resolved on the instance's type: the TypeUri that SubscribeToTypeDescription reports for that leaf. A leaf declared xsd:boolean arrives as a BoolColumn and one declared xsd:dateTime as a DateTimeColumn, whatever type the source delivered the value in. A value a source sends in another type is converted on the way out, and a value that cannot be converted is a null cell on that column, so a column never changes type between rowsets. Every column has a declared type: a type that leaves a deferred leaf unpinned does not compile (rule O-B23), so no instance you can subscribe to has an open leaf.

A relationship carries its two endpoints as columns#

Every relationship instance now carries two read-only string columns, named by the reserved atlas:Source and atlas:Target vocabulary URIs and filled at compile time with the endpoint instance URNs.

They behave as ordinary static columns rather than as anything special, so they arrive everywhere a property does: full-row and delta SubscribeToInstance and SubscribeToInstanceOfType, SubscribeToInstancePropertyOfType on either endpoint, the range reads, and GET .../instances/{instanceId}/values. You do not subscribe to them separately, and you cannot write them.

A relationship type with no properties of its own used to disappear from a snapshot. With nothing to put in a row it produced no units at all and its instances were dropped. Those two columns are enough to give it one, so a relationship-only type now shows up where it previously looked like missing data.

Describing a type before you subscribe#

The value streams carry values. A fifth method, SubscribeToTypeDescription, carries the shape of a type: its columns, its endpoints if it is a relationship, or its members if it is an enumeration.

A consumer learns a type's columns before, or without, subscribing to any instance. That lets you build your decoder up front, validate configuration against the real shape, and learn when a recompile changes it.

It behaves like the value streams: the first item is the current state, then items arrive as it changes. You consume it with StreamAsync, but it yields TypeDescriptionDto items rather than ValueRowSetDto. In the shipped .NET client the call is SubscribeToTypeDescriptionAsync(typeUri, cancellationToken).

await foreach (var description in connection.StreamAsync<TypeDescriptionDto>(
    "SubscribeToTypeDescription",
    "urn:demo:Filler",
    cancellationToken))
{
    if (description.Deleted) { /* the type is gone; the stream ends after this item */ break; }
    var columns = Leaves(description.Schema).Select(n => n.Column);   // depth-first over leaves
    RebuildDecoder(columns);
}

static IEnumerable<SchemaNodeDto> Leaves(IEnumerable<SchemaNodeDto> nodes) =>
    nodes.SelectMany(n => n.Fields is null ? new[] { n } : Leaves(n.Fields));

TypeDescriptionDto#

The members are positional, [Key(0)] to [Key(9)], in this order.

SchemaNodeDto#

The members are positional, [Key(0)] to [Key(7)].

EnumType holds KeyType (a string) and Members, a list of { Key, Name, Label? }. Key is the member's wire value in its canonical lexical form, for example "10" under xsd:integer and "true" under xsd:boolean.

Column names you can rely on#

• A root scalar's Column equals its Uri.
• A data-type property's leaves are named propertyUri.Field, and nested fields propertyUri.Field.Sub.
• A data-type property's leaves keep these names however an instance sources them, whole or field by field with the Composed strategy. A composite node from an older host names its member columns propertyUri.member, with a data-type member's leaves under that as propertyUri.member.Field.
• A relationship type carries two Endpoint leaves. Their Uri and Column are both the reserved vocabulary URIs urn:atlas:vocab:Source and urn:atlas:vocab:Target, typed xsd:string. These are the same two columns every relationship rowset carries.

Endpoints is a different fact from the two endpoint columns. The columns hold the endpoint instances. Endpoints is the constraint on which types may sit at each end.

Walking Schema depth-first over its leaves gives the exact set of columns a full-row rowset of the type carries.

When items arrive#

The first item is the snapshot. After that, one item arrives per recompile whose shape differs from the last item you received. The shape is the label, kind, parent, endpoints, the schema tree, enum bindings, or an enum's roster. A recompile that only changes values or instances emits nothing.

When a recompile removes the type, one final item arrives with Deleted = true, an empty Schema, and null Endpoints and EnumType. Then the stream completes normally. That is how you tell "the type is gone" from "the connection dropped".

Streams do not auto-restore after a reconnect, the same as the value streams. Resubscribe.

If typeUri names neither a type nor an Enumeration Type in the pinned compiled world, the stream fails with a HubException reading Could not resolve (branch/domain, typeUri).

Enumeration Types#

typeUri may also name an Enumeration Type. Its description has Kind = Enum, an empty Schema, and null ParentUri and Endpoints. The roster is in EnumType.

A roster change emits a new description. That covers a member added, removed, reordered or relabelled, and a change of key type. Removing the enum sends a tombstone.

The natural flow is:

1. Subscribe to an entity type.
2. Notice EnumTypeUri on a leaf.
3. Subscribe to that URI for the key roster.
4. Resolve raw keys to labels on your side.

The raw key on the value streams is unchanged by any of this. The description is metadata only.

The usual pattern#

Describe the type, build your decoders from the leaf columns, call a GetRange* method to fill the window, then call a Subscribe* method to keep it current. Keep the description stream open so that a recompile which changes the shape tells you to rebuild.

Reading history over the same connection#

Four more methods return stored ranges. They stream in exactly the same way.

The bounds are .NET ticks, not Unix epoch. fromTicks and toTicks are long tick values, where one tick is 100 nanoseconds and the epoch is 0001-01-01. Passing Unix milliseconds gives you a window in the first century and an empty result with no error. In .NET use DateTime.Ticks; from another platform, convert explicitly.

An atomic property, meaning one with no time axis, yields a single current-value row rather than a series, which is the expected shape.

The usual pattern for a chart is one GetRange* call to fill the window, then a Subscribe* call to keep it current. To build the decoder first, see Describing a type before you subscribe.

Errors and traps#

Related articles#

• Atlas API Overview - the route table, auth policies and error envelope
• Registering Timebase apps as OAuth clients in Pulse - audiences and the bearer token
• Exporting Data with Bridge - the shipped consumer of this hub
• How Atlas Aligns and Times Values - watermarks, anchors and the lateness gate
• Timebase Atlas Architecture - where the hub sits