LogoLogo
Contact Uscybus.io
Connectware 1.9.0
Connectware 1.9.0
  • Getting Started
    • Introduction
    • Installing Connectware
      • System Requirements
      • Acquiring your License Key
      • Installing Connectware on Docker
      • Installing Connectware on Kubernetes
    • Connectware Admin UI
    • Basic Components of Connectware
    • Connecting your First Machine
      • Your First Service Commissioning File
  • Documentation
    • Services
      • Service Commissioning Files
        • Structure of Service Commissioning Files
          • description
          • metadata
          • parameters
          • definitions
          • resources
            • Cybus::Connection
            • Cybus::Endpoint
            • Cybus:Mapping
            • Cybus::Container
              • Docker problem with network changes
            • Cybus::Link
            • Cybus::IngressRoute
            • Cybus::User
            • Cybus::Role
            • Cybus::Volume
            • Cybus::File
            • Cybus::Server
            • Cybus::Node
        • Sample Service Commissioning Files
          • Modbus
            • “Bearbeitungszentrum BAZ” - Single File
            • “Bearbeitungszentrum BAZ” - Multiple Files
            • “Bearbeitungszentrum BAZ” - Single File and Custom Topics
            • “Bearbeitungszentrum BAZ” - Agent Mode
          • Machine Condition Monitoring : OPC UA + InfluxDB + Grafana Dashboard
            • “Machine Condition Monitoring Example” - Single File
          • Machine Utilization Example (Multi file service composition) : Modbus TCP + InfluxDB + Grafana + MSS
            • “Machine Utilization Example” - Machine Connectivity
            • “Machine Utilization Example” - Dashboards with role based access permission
            • “Machine Utilization Example” - Push data to MSSQL Database
      • Services View
      • Setting Up and Configuring Services
        • Installing Services
        • Enabling Services
        • Updating Services
        • Disabling Services
        • Deleting Services
      • Service Details View
      • FlowSync
        • Example 1 - Node with Transaction Mode (HTTP)
        • Example 2 - Node Responds (HTTP)
        • Example 3 - Node with Error (HTTP)
        • Example 4 - Node with Timeout Error Code and Error Message (HTTP)
        • Example 5 - Full Transactional Data Flow (HTTP)
        • Example 6 - Full Transactional Data Flow (OPC UA)
      • ServiceID
      • Inter-Service Referencing
      • Deviation
      • Service Logs
        • Logs of Individual Services
        • Logs of All Services
      • Rule Engine
        • Data Processing Rules
        • Rule Sandbox
      • Shared Subscriptions
        • Setting Up Shared Subscriptions
      • API Definition
    • Resources
      • Servers
      • Containers
      • Volumes
      • Connections
      • Endpoints
      • Mappings
      • Nodes
      • API Definition
    • User Management
      • Users and Roles View
      • Users
      • Roles
      • Permissions
      • Password Policy Rules
      • Default Admin User
      • MQTT Users
      • Adding a MQTT Publish Prefix for Users
      • Multi-Factor Authentication
      • Long lived JSON Web Tokens
      • Access Permissions for Admin-UI
        • UI Access
        • Minimum Access Role Pages
      • API Definition
    • Client Registry
      • Implicit Flow
      • Explicit Flow
      • Granting Access
      • API Definition
    • Certificates
    • Monitoring
      • Data Explorer
      • Live Data
    • Workbench
      • Flows in Git Repositories
    • System Status
      • Info
      • Metrics
      • Status
      • Retrieving More System Information
      • System Health
      • API Definition
    • Backup and Restore
      • Volumes
      • User Database
    • Configuration
      • Environment Variables
      • LDAP Configuration
      • MFA Configuration
    • Agents
      • Agents View
      • Installing Agents
        • Installing Agents via Docker
        • Installing Agents via Docker Compose
        • Installing Agents via Kubernetes
        • Using Mutual TLS for Agents
      • Registering Agents in Connectware
      • Using Agents
      • Monitoring Agents
      • Troubleshooting Agents
    • Industry Protocol Details
      • ADS
        • AdsConnection
        • AdsEndpoint
      • BACnet
        • BacnetConnection
        • BacnetEndpoint
      • EtherNet/IP
        • EthernetIpConnection
        • EthernetIpEndpoint
      • Focas
        • FocasConnection
        • FocasEndpoint
      • Generic VRPC
        • GenericVrpcConnection
        • GenericVrpcEndpoint
      • Hottinger Baldwin Messtechnik (HBM)
        • HbmdaqConnection
        • HbmdaqEndpoint
      • Heidenhain DNC
        • HeidenhainConnection
        • HeidenhainEndpoint
      • HTTP/REST
        • HttpConnection
        • HttpEndpoint
      • HTTP Server
        • HttpServer
        • HttpNode
      • InfluxDB
        • InfluxdbConnection
        • InfluxdbEndpoint
      • Kafka
        • KafkaConnection
        • KafkaEndpoint
      • Modbus/TCP
        • ModbusConnection
        • ModbusEndpoint
      • MQTT
        • MqttConnection
        • MqttEndpoint
      • MSSQL
        • MssqlConnection
        • MssqlEndpoint
      • OPC DA
        • OpcdaConnection
        • OpcdaEndpoint
      • OPC UA
        • OPC UA Client
          • OpcuaConnection
          • OpcuaEndpoint
        • OPC UA Server
          • OpcuaServer
          • OpcuaNode
        • OPC UA Object Types
        • OPC UA Server References
          • OpcuaReferenceNode
          • OpcuaObjectNode
      • Siemens SIMATIC S7
        • S7Connection
        • S7Endpoint
      • Shdr
        • ShdrConnection
        • ShdrEndpoint
      • Sinumerik
        • SinumerikConnection
        • SinumerikEndpoint
      • Sopas
        • SopasConnection
        • SopasEndpoint
      • SQL
        • SqlConnection
        • SqlEndpoint
      • Werma WIN Ethernet
        • WermaConnection
        • WermaEndpoint
      • Systemstate
        • SystemstateConnection
        • SystemstateEndpoint
      • API Definition
    • Connectware Licensing
    • Changelog
      • General changes from 0.x to 1.0
        • Upgrading from 0.x to 1.0
    • Upgrade Guide
      • Upgrading from 1.x to 1.7.0
      • Upgrading from 1.x to 1.5.0
Powered by GitBook
LogoLogo

Cybus

  • Terms and Condition
  • Imprint
  • Data Privacy

© Copyright 2025, Cybus GmbH

On this page
  • Syntax of Shared Subscriptions
  • Shared Subscriptions Examples
  • Basic Example with One Agent
  • Advanced Example with Two Agents (Load Balancing)
  • Advanced Example with Multiple Agents (Wildcard Mappings)

Was this helpful?

  1. Documentation
  2. Services
  3. Shared Subscriptions

Setting Up Shared Subscriptions

Learn about setting up shared subscriptions in Connectware.

In Connectware, you can use shared subscriptions with mappings and endpoints. Below, we provide three service commissioning file examples that demonstrate different use cases for implementing shared subscriptions.

Syntax of Shared Subscriptions

The syntax for shared subscriptions follows this pattern:

$share/group_name/topic
Parameter
Description
Required

$share

A fixed prefix that designates a shared subscription.

Yes

group_name

An identifier for the group of clients that will share the message load. All clients using the same group name will be part of the same message distribution group.

Yes

topic

The actual topic pattern to subscribe to. Can include wildcards and multi-level topics according to standard MQTT topic rules.

Yes

Example

$share/processing_group/sensors/data

In this example:

  • All clients subscribing with this pattern will be part of the processing_group

  • Messages published to sensors/data will be distributed among these clients

  • Each message will be delivered to exactly one client in the group, preventing duplicate processing

Shared Subscriptions Examples

Basic Example with One Agent

This example allows you to test if shared subscriptions work correctly by forwarding messages published to the input topic to the mapping subscribed to $share/group1/input.

  1. Publish a message to the input topic.

Result: The agent will publish to the topic output.

description: |
    Simple Mapping with Shared Subscription

metadata:
    name: Simple Shared Subscription

resources:
    sharedSubscriptionMapping:
        type: Cybus::Mapping
        properties:
            mappings:
                - subscribe:
                      topic: $share/group1/input
                  publish:
                      topic: output
                  rules:
                      - transform:
                            expression: |
                                {
                                  "msg": $
                                }

Advanced Example with Two Agents (Load Balancing)

This example allows you to test the load-balancing capability of shared subscriptions using two agents.

  1. Publish a message to the input topic.

Result: Either agent01 or agent02 will publish to the output topic, but only one will act at a time. This ensures load balancing between the agents.

description: |
    Shared Subscription Test

metadata:
    name: Shared Subscription Test

parameters:
    agentName:
        description: Choose Agent
        type: string
        enum: ['agent01', 'agent02']

resources:
    sharedSubscriptionMapping:
        type: Cybus::Mapping
        properties:
            agentName: !ref agentName
            mappings:
                - subscribe:
                      topic: $share/group1/input
                  publish:
                      topic: output
                  rules:
                      - transform:
                            expression: !sub |
                                (
                                  $merge([$, {"agent": "${agentName}"}]);
                                )

Advanced Example with Multiple Agents (Wildcard Mappings)

In this example, a shared subscription is deployed across multiple agents. This example sets up a qa group where agents subscribe to the service/# topic wildcard, allowing them to handle messages on all subtopics. This setup is particularly useful for load testing, where tens of thousands of messages per second are processed from sources like OPC UA. The agents then publish these messages to the northbound/opcua/$nodes topic.

The wildcards #nodes and $nodes represent a named wildcard that maps the topic tree under services (e.g., service/a/bc, service/x/y/z/...) to the northbound path (e.g., northbound/opcua/a/bc).

The dedicated connection specified in the subscribe property ensures that each agent creates a new MQTT client instead of sharing a single MqttConnection.

---
description: |
    Wildcard Mapping with Shared Subscription

metadata:
    name: Wildcard Mapping Shared Subscription
    provider: cybus
    homepage: https://www.cybus.io
    version: 1.0.0

parameters:
    agentName:
        type: string
        default: protocol-mapper

    mqttBroker:
        type: string
        default: broker.example.com

    mqttUser:
        type: string
        default: admin

    mqttPassword:
        type: string
        default: admin

resources:
    mqttConnection:
        type: Cybus::Connection
        properties:
            agentName: !ref agentName
            protocol: Mqtt
            targetState: connected
            connection:
                host: !ref mqttBroker
                username: !ref mqttUser
                password: !ref mqttPassword

    wildcardMappingSharedSubscription:
        type: Cybus::Mapping
        properties:
            agentName: !ref agentName
            mappings:
                - subscribe:
                      topic: $share/qa/services/#nodes
                      connection: !ref mqttConnection
                  publish:
                      topic: northbound/opcua/$nodes
PreviousShared SubscriptionsNextAPI Definition

Last updated 5 months ago

Was this helpful?

Install an agent. See .

Register the agent in Connectware. See .

Apply the service to the agent. See .

Enable the services. See .

Install two agents named agent01 and agent02. See .

Register the agents in Connectware. See .

Apply the same service to both agents (rename one for differentiation). See .

Enable the services. See .

Installing Agents
Registering Agents in Connectware
Installing Services
Enabling Services
Installing Agents
Registering Agents
Installing Services
Enabling Services