Getting started with OctoMesh

In this tutorial you learn the handful of concepts everything else in OctoMesh builds on, find your way around the Refinery Studio and set up octo-cli so you can work from the command line. Nothing in this tutorial changes data.

Time: about 30 minutes.

Core concepts

OctoMesh is a data platform: it stores what things are (master data, a model of your world) and what they measure (time series), and it moves data in and out through pipelines. Six terms carry most of the weight.

Tenant

A tenant is an isolated workspace with its own database, users, roles and configuration. Every request you make names a tenant, either in the URL (/tenants/<tenant>/GraphQL) or through the token you log in with. Tenants can form a hierarchy: a parent tenant can host shared applications and child tenants for individual customers or projects. See Tenant Lifecycle.

Construction Kit (CK)

A Construction Kit is the data model of a domain. It is versioned and published as a library (for example Basic.Energy-1.9.0 or EnergyCommunity-4.9.0) and contains:

• Types, which are like classes with inheritance. A CK type id is written <Model>/<Type>, for example EnergyCommunity/Customer.
• Attributes: the typed fields of a type (string, number, date time, enum, record, ...).
• Records: structured values without their own identity, for example an address or a time range.
• Enums: closed value lists, for example the data quality L1, L2, L3.
• Associations: typed relationships between types, for example the parent/child relation System/ParentChild.

A tenant uses a CK once the library is imported into it. See Construction Kits.

Runtime entity

A runtime entity is an instance of a CK type: one concrete customer, one metering point. Every entity has

• an rtId, a 24-character hexadecimal id that is unique within the tenant,
• a ckTypeId that names its type,
• optionally an rtWellKnownName, a stable name you can look it up by,
• attribute values and associations to other entities.

The entities of a tenant form its runtime model, which is stored in MongoDB and queried through GraphQL.

Stream data, archives and rollups

Values that change over time, such as a meter reading every 15 minutes, are stream data. They are not stored on the entity itself but in an archive: a time-series table in CrateDB, one row per entity and point in time (or per time window). The entity acts as the anchor of its time series: the rtId of the row points to it.

• A raw archive or time-range archive receives the original values.
• A rollup archive aggregates another archive into coarser buckets (hourly, daily, monthly, ...) automatically, so long time ranges can be read without summing millions of raw rows.

See Stream Data and Archives.

Blueprint

A blueprint is an installable package for a tenant. It names the CK libraries it needs and brings seed data: configuration entities, queries, dashboards, archives and pipelines. Installing a blueprint turns an empty tenant into a working application. See Blueprints.

Pipelines, data flows and adapters

A pipeline is a sequence of nodes that is triggered by an event (a schedule, an HTTP request, a message), transforms data and writes the result into the runtime model, an archive or an external system. Pipelines are grouped into data flows and run on an adapter, a service that is deployed for the tenant. The Mesh Adapter runs general-purpose pipelines, other adapters connect to specific systems (for example SAP, Modbus or the Austrian energy data exchange EDA). See Communication.

A tour of the Refinery Studio

The Refinery Studio is the web interface of OctoMesh. Open https://studio.<your-domain>/<tenant> and log in with your account. The exact labels in the navigation depend on your Studio version and your roles, but you will find these areas:

Area	What you do there	Reference
Data explorer / Repository	Browse runtime entities by CK type, open an entity, follow its associations, edit attributes (if your role allows it)	Refinery Studio
Model libraries	See which CK libraries are installed in the tenant and inspect their types, attributes and enums	Model libraries
Query builder	Build and save queries over runtime entities and stream data without writing GraphQL	Query builder
Archives	See the stream-data archives of the tenant, their status and their rollups	Archives
Blueprints	See which blueprints are installed and in which version	Blueprints
MeshBoards	Dashboards built from saved queries	MeshBoards
Communication	Adapters, data flows and pipelines with their execution history	Communication
Identity	Users, groups, roles and OAuth clients of the tenant (administrators only)	Identity

Try this short round trip:

1. Open Model libraries and note the libraries your tenant uses.
2. Pick one type of a domain library and open it in the data explorer. Note the rtId of one entity; you will use it again in the next tutorial.
3. Open Archives and check whether the tenant has archives and whether they are Activated. Only activated archives hold data.

Working from the command line with octo-cli

octo-cli is the command-line tool for OctoMesh. You need it to log in from scripts and to run administrative commands. See the installation instructions.

Create a context

A context bundles the service URLs, the tenant and the stored tokens, like a kubectl context. Create one per tenant you work with:

octo-cli -c AddContext -n <context-name> \
  -isu https://connect.<your-domain>/ \
  -asu https://assets.<your-domain>/ \
  -bsu https://bot.<your-domain>/ \
  -csu https://communication.<your-domain>/ \
  -tid <tenant>

The first context you add becomes the active one. Switch with octo-cli -c UseContext -n <context-name> and list all contexts with octo-cli -c ListContexts. Any command can also target a context explicitly with --context <context-name>, without changing the active one.

Log in

octo-cli -c LogIn -i

octo-cli uses the OAuth device flow: it opens a browser (or prints a URL and a code), you log in as usual, and the CLI receives an access token and a refresh token. Both are stored in the context file ~/.octo-cli/contexts.json.

Check the login:

octo-cli -c AuthStatus

AuthStatus refreshes an expired access token automatically if the refresh token is still valid, so an expired message is usually not a reason to log in again. For scripts that run often, octo-cli -c LogIn -i -in logs in only when the stored token can no longer be refreshed.

Treat the context file like a password

~/.octo-cli/contexts.json contains your tokens, and AuthStatus prints the access token. Never paste either into a chat, a ticket or a repository.

First read-only commands

# Which CK libraries are installed in the tenant, and in which version?
octo-cli -c LibraryStatus

# Which blueprints are installed?
octo-cli -c ListBlueprintInstallations

LibraryStatus lists every library with its installed and available version and its state; Available means the model is healthy. For the full list of commands see the command reference and the common workflows.

Summary

• A tenant holds a runtime model of entities whose types come from Construction Kits.
• Time series live in archives, anchored to entities by rtId, and are aggregated by rollups.
• Blueprints install models, configuration and pipelines in one step.
• The Refinery Studio is the visual way in, octo-cli the scriptable one.

Next: Accessing data shows you how to query all of this from your own code.