228 docs tagged with "Technology"

Activates a CkArchive: provisions the per-archive CrateDB table and transitions the archive to Activated. Use this once after rt-importing the archive entity.

Adds a new identity provider for active directory.

Adds a new client using grant type 'AuthorizationCode'.

Adds a new identity provider for Microsoft Azure Entra ID.

Adds a new client using grant type 'ClientCredentials'.

Adds or updates a named context.

Adds a new client using grant type 'device code'.

Adds a child group to a parent group.

Adds a new identity provider.

Adds a new identity provider for cross-tenant authentication via a parent tenant.

Adds a new identity provider for Open LDAP.

Grants the access to a client for a scope .

Adds a user to a group.

Adds an user to a role

Aggregation queries compute summary values (averages, totals, extremes) across time-series data points instead of returning individual rows. Use these when you need calculated metrics rather than raw data — for example, the average voltage over the last hour or the total energy produced per machine.

Association Roles define the relationship types between entities. Each role specifies the multiplicity and naming for both directions of the relationship (inbound and outbound).

Associations define relationships between entities in the runtime model. This chapter describes how to query and navigate associations.

Attach an existing database to a tenant.

Attributes are reusable property definitions that can be applied to types. Each attribute has a value type and optional constraints.

OctoMesh uses OAuth 2.0 and OpenID Connect (OIDC) for authentication. This page explains how authentication works, which flows are supported, and what happens during the login process.

Gets authentication status to the configured identity services.

AutoIncrements provide automatic value generation for attributes when entities are inserted into the repository. They ensure unique, sequential values for attributes like customer numbers, document IDs, or any other identifier that requires automatic numbering.

This chapter provides best practices for writing efficient and maintainable GraphQL queries and mutations.

This section provides best practices and recommendations for creating construction kits.

Blueprints are versioned, declarative bundles of Construction Kit (CK) models and runtime seed data that bootstrap a tenant — and continue to manage it across its lifetime. A blueprint can be installed, re-applied, updated, rolled back, uninstalled, and may depend on other blueprints. Versioned migration scripts transform tenant data when a blueprint's own version moves forward.

Shows the dependency tree for a CK model from a catalog.

Pre-flight check for CK model upgrade/migration.

Resets a tenant to factory defaults by deleting the construction kit and runtime model.

Clears the cache of a tenant

In OAuth 2.0, a client is any application that requests access on behalf of a user or itself. API scopes define what operations a client is allowed to perform. The Identity Service manages both per tenant.

Multi-command playbooks for typical octo-cli usage scenarios. Each step has its own copyable code block — paste them one at a time. Full per-command documentation is in the Command Reference sidebar section.

Configures the active context.

The Construction Kit defines the schema and structure of your data model. Unlike the Runtime Model which stores actual data instances, the Construction Kit contains the metadata that defines what types of entities can exist, their attributes, relationships, and constraints.

GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be created.

Creates a new tenant and provisions the current user as admin.

Creates an admin provisioning mapping in a target tenant.

Adds a new api resource.

Creates a new API scope.

Adds new API secret for an API resource.

Adds new API secret for a client.

Creates an email domain group rule.

Creates an external tenant user mapping.

Creates a fixup script

Creates a group.

Create a new role

Create a new user account

OctoMesh supports a hierarchical tenant model where a parent tenant can authenticate users in child tenants. This allows organizations to maintain a single user directory while granting access to multiple isolated tenants.

This document explains the fundamental data modeling concepts in OctoMesh, including Construction Kits, Runtime Entities, and Stream Data.

GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be deleted.

Deletes an existing tenant.

Deletes an admin provisioning mapping from a target tenant.

Deletes an api resource.

Deletes an API scope.

Deletes a secret of an API resource.

Deletes a secret of a client.

Drops the per-archive CrateDB table and soft-deletes the CkArchive entity. Destructive — historical data is lost.

Deletes a client.

Deletes an email domain group rule.

Deletes an external tenant user mapping.

Deletes a group.

Deletes an identity provider.

Deletes a role

Deletes an user

Deploys a specific data flow.

This page lists the hosted MCP (Model Context Protocol) Services endpoints and how to register each with your AI client. For the registration mechanics see Getting started.

Deploys a pipeline definition to the corresponding adapter.

Deploys all triggers for the current tenant.

Triggers a deploy of one workload (Adapter or Application) through its parent pool.

Detach tenant.

Disables the AI Adapter for the current tenant. The seeded AgentConfig and CK model are not removed; re-enabling is idempotent.

Disables a CkArchive: transitions to Disabled (data preserved). Allowed only from Activated.

Disables the communication controller for the current tenant.

Disables reporting services for the current tenant.

Disable stream data services for the current tenant.

A downsampling query reduces the density of time-series data by dividing a time range into equal-sized buckets and applying an aggregation function to each bucket. This is essential for visualizing large datasets on dashboards and charts — instead of transferring thousands of raw data points, you get a manageable number of summarized values.

Dumps a tenant to a file

Email domain group rules automatically assign users to groups based on their email address domain. When a user registers or logs in for the first time, the Identity Service checks their email against configured rules and adds them to matching groups.

Enables the AI Adapter for the current tenant. The Communication Controller must be enabled first (run EnableCommunication beforehand).

Re-enables a previously disabled archive: transitions Disabled → Activated. Re-validates column paths against the current CK model; no DDL.

Enables the communication controller for the current tenant.

Enables reporting services for the current tenant.

Enable stream data services for the current tenant.

Enums are used for establishing a set of predefined constants, which can represent various states, types, or configurations within the library. Enums are embedded within a Runtime Entity Object and do not need any navigation through associations.

Enums define a fixed set of allowed values for an attribute. Each enum value has a numeric key, a name, and an optional description.

This chapter describes how errors are returned in GraphQL responses and how to handle them.

Executes a pipeline and returns the execution ID.

Schedules a job to export runtime model graph by providing RtId's and type as starting point. File is specified using -f argument. The file is downloaded in ZIP-format after job is finished.

Schedules a job to export runtime models using a query. File is specified using -f argument. The file is downloaded in ZIP-format after job is finished.

Imports all CK models that need update or fix. Use -w to wait, -y to skip confirmation.

Fixup Scripts are MongoDB-compatible scripts that can be applied to databases for maintenance, migration, and data correction tasks. They are executed by the bot service in a defined sequence order, ensuring consistent and predictable database modifications.

Freezes a CkRollupArchive at the given timestamp. Monotonic — rejected when the new value is earlier than the current FrozenUntil. The orchestrator stops producing buckets whose bucketEnd falls within the frozen range; already-aggregated rows are preserved.

Generate CA and service/server certificates to run OctoMesh operator

Gets the configuration for a specific adapter.

Gets aggregated node descriptors from all connected adapters.

Gets all adapters for the current tenant.

Gets admin provisioning mappings for a target tenant.

Returns the AI credential-lease status (expiries + generation) for the active tenant. Token plaintext is never disclosed.

Gets all api resources.

Gets all api scopes.

Gets all secrets of an API resource.

Gets all secrets of a client.

Shows the blueprint application history for the current tenant.

Gets a client by its ID.

Lists the sub-tenants a ClientCredentials client has been auto-provisioned into.

Gets all clients.

Gets the status of a specific data flow.

Gets an email domain group rule by ID.

Gets all email domain group rules.

Gets an external tenant user mapping by ID.

Gets external tenant user mappings.

Gets a group by ID.

Gets all groups.

Gets all identity providers.

Returns the latest pipeline execution.

Gets the debug state of a pipeline.

Returns debug point nodes for a specific pipeline execution.

Returns pipeline execution history.

Gets the pipeline JSON schema for a specific adapter.

Gets the deployment state of a pipeline.

Gets all pools for the current tenant.

Gets roles.

Gets all child tenants.

This page walks you through registering the MCP (Model Context Protocol) Services with an AI client and making your first authenticated tool call. The hosted endpoints are listed on the Deployments page.

Gets users.

Lists every Adapter / Application in the active tenant whose ChartName matches.

Groups are organizational units that simplify role management. Instead of assigning roles to each user individually, you assign roles to a group and then add users to that group.

Identity providers allow users to authenticate with OctoMesh using external identity systems. Each tenant can configure multiple providers independently.

The OctoMesh Identity Service provides centralized authentication and authorization for the entire platform. It supports OAuth 2.0 and OpenID Connect protocols.

Schedules an import job for construction kit files. File is specified using -f argument. To wait for job, use -w argument.

Imports a CK model from a catalog with all dependencies. Use -w to wait for completion.

Schedules an import job for runtime files. File is specified using -f argument. To wait for job, use -w argument.

OctoMesh uses Communication Operators to manage distributed computing resources using Kubernetes. The Communication Operators are responsible for managing the lifecycle of the Adapters, including creating, updating, and deleting Adapters.

Installs a blueprint into the current tenant. CK models are loaded and seed data is imported via upsert.

In the realm of OctoMesh, adapters and pipelines play a crucial role as the connective tissue between the OctoMesh platform and external data sources and services. These small, but powerful pieces of software are designed to facilitate communication and data exchange across a diverse set of endpoints, including APIs, file systems, databases, message brokers, and other custom or standard protocols. To cater to different architectural needs and deployment scenarios, OctoMesh distinguishes between two main types of adapters: Edge Adapters and Mesh Adapters.

At the heart of OctoMesh lies the concept of Construction Kits. These kits serve as a fundamental building block for defining object models and providing the essential context that transforms data into actionable insights. With OctoMesh, you can construct models that align with your specific needs, allowing you to shape data in ways that make sense for your organization.

Welcome to the OctoMesh Technology Guide, your comprehensive resource for leveraging the transformative power of OctoMesh to architect and manage robust data mesh solutions. This guide is crafted to serve as your navigator through the expansive features of OctoMesh, shedding light on the underlying concepts, providing detailed how-to instructions, and offering practical recipes that help you harness the full potential of your data.

OctoMesh provides built-in tools for managing Construction Kit (CK) model libraries across tenants. This includes browsing available libraries from catalogs, checking compatibility, resolving dependencies, and importing libraries with full dependency resolution.

Shows installed CK model libraries with catalog availability. Use --needs-action to filter.

Lists tenant backups created before blueprint updates.

Lists all blueprints currently installed on the active tenant.

Lists blueprints available across configured catalogs.

Lists CK models from catalogs. Use -cn to filter by catalog, -q to search.

Lists available CK model catalog sources.

Lists all configured contexts. Pass -n to show details for a single context.

Lists every rollup archive attached to the given source CkArchive — runtime id, status, schedule, watermark, freeze state.

LogIn to the configured identity services.

Non-interactive login using OAuth2 clientcredentials. Reads credentials from -id/-s arguments or OCTOCLICLIENTID/OCTOCLICLIENT_SECRET env vars. Tenant comes from the active context.

The Maintenance Dashboard allows to get insights about costs and maintenance activities. It provides a comprehensive overview of the maintenance status of the assets and the costs associated with the maintenance activities. The dashboard is designed to help maintenance managers and technicians to monitor the maintenance activities, track the costs, and identify potential issues that require immediate attention.

The OctoMesh MCP (Model Context Protocol) Services is the Model Context Protocol server for OctoMesh. It exposes the platform's full administrative surface — tenants, identity, blueprints, communication adapters, time-series archives, generic Construction Kit entity CRUD, and aggregation queries — as ~177 typed tools that AI assistants (Claude Code, Claude Desktop, and any other MCP-capable client) call over HTTP+SSE.

When a Construction Kit (CK) model evolves to a new version, existing runtime entities in tenant databases may need to be updated to match the new schema. CK model migrations automate this process by defining versioned transformation scripts that update entity data (rename types, change attributes, etc.) during model import.

Models are containers that group related types, attributes, enums, and records. Each model has a name, version, and can depend on other models.

Reassigns one or more pipelines from their current adapter to a new target adapter. Each pipeline is moved atomically; per-pipeline failures do not abort the batch. Source and target adapter must share the same CkTypeId.

octo-cli is the command-line interface for managing and administering OctoMesh. It provides commands for configuring services, managing tenants, users, identity providers, and more.

service coreServices(common:meshLogo)[Core Services] in central

Adapters are executing pipelines and pipeline consists of nodes. There are nodes that are common for all adapters and there are nodes that are specific for each adapter. For example the Modbus adapter comes with Modbus nodes, the OPC UA adapter comes with OPC UA nodes, etc.

The integration of OctoMesh with SAP provides a seamless and efficient way to exchange data between the two systems. Leveraging the SAP NetWeaver SDK,

In OctoMesh, data pipelines are integral to the Extract, Transform, Load (ETL) processes that ensure efficient data handling across distributed environments. Pipelines are executed by Adapters, which can be deployed either at the edge (close to data sources) or centrally in the cloud.

Pipeline triggers are used to start the execution of a pipeline based on a cron schedule using the Bot Service.

OctoMesh uses Communication Operators to manage distributed computing resources using Kubernetes. The Communication Operators are responsible for managing the lifecycle of the Adapters, including creating, updating, and deleting Adapters.

In OctoMesh, we understand that data is at the heart of your operations. This chapter focuses on how you can access and interact with your data through our Construction Kits (CK), tailored for both runtime data and stream (time series) data. Leveraging GraphQL endpoints, OctoMesh offers a seamless and efficient way to work with your data, regardless of its nature.

Persisted queries are saved query definitions stored as runtime entities. Instead of specifying all query parameters every time, you create a query definition once and execute it by its rtId. This is useful for dashboard widgets, recurring reports, and any scenario where the same query needs to be executed repeatedly.

Edge and Mesh Pipelines enable the data flow between the edge and the mesh (cloud) environment. The Edge Pipelines are responsible for preprocessing the data before sending it to the Mesh Pipelines. The Mesh Pipelines are responsible for processing the data in the cloud environment.

OctoMesh is operated using Kubernetes in production. These docs describe a possibility to run OctoMesh on a local docker environment.

Previews the changes a blueprint update would make without applying them.

Backfill: provisions a flagged ClientCredentials client into every existing sub-tenant of the active context tenant. Idempotent.

Manually provisions a flagged ClientCredentials client into one specific sub-tenant.

Provisions the current user in a target tenant.

Reconfigures the log level for services

Records are composite value types that group related attributes together. Unlike types, records are embedded directly within entities rather than being independent entities with their own runtime IDs.

Redeems a one-time AI credential ticket and persists the Anthropic subscription tokens on the AI Adapter. Runs anonymously — the ticket code authenticates the call, no OctoMesh login required. Token-related args (-at -rt -aex -rex) are optional for developer smoke tests; missing values default to a fake pair with a far-future expiry.

Refreshes CK model catalog caches. Use -cn to refresh a specific catalog.

Removes a named context.

Removes a child group from a parent group.

Removes a user from a group.

Remove an user from a role

OctoMesh provides comprehensive backup and restore capabilities for repositories through the octo-cli tool. These

Resets the password of a user

Restore a tenant from a dump file

This chapter describes common query patterns for retrieving Construction Kit metadata. The Construction Kit API is read-only - you query the model structure but cannot modify it through GraphQL.

API Approaches

Retries activation after a previous DDL failure. Allowed only from Failed.

Revokes the active tenant's AI credential lease. New sessions cannot start until a fresh subscription is registered. Ciphertext is preserved for audit.

Resets the rollup's watermark (truncated down to the bucket boundary) so subsequent orchestrator ticks re-aggregate the rewound range. Destructive: rows in that range are temporarily out of sync until the orchestrator catches up.

Rolls the active tenant back to a previously-created blueprint backup.

This guide walks you through setting up OctoMesh locally using Docker containers.

Run fixup scripts

GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be created, retrieved, updated and deleted. It provides a reference for the GraphQL scalar types, input types, and enums used in the OctoMesh GraphQL API.

The SearchFilter provides text search capabilities across multiple attributes of an entity. It is optimized for text-based searches and is typically used for search fields in list views.

Flips the AutoProvisionInChildTenants flag on an existing ClientCredentials client. Flipping to true does not auto-backfill — use ProvisionClientInExistingTenants for that.

Enables or disables debug capture for a pipeline.

Sets identity services up

A simple query retrieves raw time-series rows from CrateDB. You choose which columns to return and can apply filters, sorting, and time range restrictions. This is the most fundamental stream data query type — use it when you need individual data points rather than aggregated summaries.

This document provides a comprehensive overview of the OctoMesh platform architecture, designed to help developers understand the system components, data flows, and integration patterns.

Start creating libraries

Stream data provides access to time-series data stored in CrateDB. While runtime queries retrieve the current state of entities from MongoDB, stream data queries retrieve historical measurements and events recorded over time — such as sensor readings, machine metrics, or energy production values.

A Stream Data Archive is the unit of configuration and storage for time-series data in OctoMesh. Each archive is a versioned, typed, per-tenant CrateDB table that captures a curated set of attribute paths from a Construction Kit type. Archives have a strict lifecycle (Created → Activated → Disabled / Failed), an immutable schema once activated, and a three-tier activation gate (instance → tenant → archive) that determines whether the data plane is open.

This chapter describes how to create System Queries. For an overview of System Queries and their use cases, see System Queries.

System Queries are reusable query configurations stored in the repository. They allow you to define a query once and execute it from multiple places using only its ID.

This chapter describes how to update System Queries. For an overview of System Queries and their use cases, see System Queries.

This guide explains what happens when tenants are created, attached, or restored, and what steps you need to take in each scenario.

The MCP (Model Context Protocol) Services exposes ~177 tools as of version 1.5.3, grouped into the families below. Most platform-admin tools mirror the matching octo-cli command (snakecase names — e.g. CLI CreateTenant → MCP createtenant); the aggregation and persisted-query tools mirror the asset-repository's GraphQL transient-query surface.

Transient queries allow you to dynamically query runtime entities with configurable column paths. Unlike regular queries where the returned fields are defined in the GraphQL query itself, transient queries return data in a table-like structure with rows and cells.

Common failure modes and how to fix them. The MCP (Model Context Protocol) Services never throws out of a tool — every problem comes back as IsSuccess: false plus an ErrorMessage. Read the message first; the table below maps the typical messages to root causes.

Types define the structure of entities in the Runtime Model. Each type has attributes, can inherit from a base type, and can participate in associations with other types.

Undeploys a specific data flow.

Undeploys all triggers for the current tenant.

Undeploys one workload (Adapter or Application) through its parent pool. Destructive — the operator helm-uninstalls the chart.

Clears FrozenUntil on a CkRollupArchive. Idempotent. Pass --acceptGaps when source data inside the previously frozen range has been truncated and the resulting gaps are acceptable.

Removes a blueprint from the active tenant; with --cascade, dependents and orphan dependencies go too.

Removes a single client mirror (drops the child-side client + the parent's tracking row).

GraphQL allows to query and mutate data. Mutations are operations like create, update and delete. This chapter describes how data can be updated.

Updates an api resource.

Updates an API scope.

Updates an API secret for an API resource.

Updates an API secret for a client.

Applies a blueprint update to the active tenant.

Updates an existing client.

Updates an email domain group rule.

Updates an external tenant user mapping.

Updates a group.

Updates the roles assigned to a group.

Updates an identity provider.

Updates a role

Updates the system construction kit model of a tenant to the latest version.

Updates an user

Sets ChartVersion on a single workload. Does NOT trigger a deploy — call DeployWorkload afterwards if needed.

Switches the active context.

Users