Systemstate

The Systemstate protocol enables you to monitor state changes across all Connectware resources. For any object with a Resource ID, you can either query the current state using read operations or subscribe to receive ongoing state change notifications using subscribe operations.

Systemstate Configuration

Below is the format for configuring the Systemstate protocol in your service commissioning file. A complete working example is provided at the end of this topic.

Resource Deployment: All Systemstate resources are deployed via Resource Status Tracking (RST). The agentName property is ignored for Systemstate resources.

Configuring Connections

Systemstate establishes an internal connection to monitor the Connectware's state management system.

• Configure your connection object as follows:

eventsConnection:
  type: Cybus::Connection
  properties:
    protocol: Systemstate
    connection: {}

Systemstate Connection Properties

protocol (required)

Must be set to Systemstate.

Systemstate Endpoints Properties

See Systemstate Endpoint Properties.

Configuring Endpoints

Each Systemstate connection can support multiple endpoints that specify which operations are available.

Two operation types are available:

• subscribe: Sends a message with state information each time the specified resource changes state.

• read: Allows querying the current state by sending any message to the topic with suffix req, and receiving the response on a topic with suffix res.

Tracking Individual Resources vs. Services

Systemstate supports two types of tracking:

Individual Resource Tracking

Track specific resources within a service (endpoints, connections, etc.) by specifying the full component identifier:

• Service ID

• Resource ID

• Format: ServiceID-ResourceID (separated by a - hyphen)

This is the recommended approach for detailed monitoring of specific components.

Service-Level Tracking

Track the entire service's enabled/disabled status by specifying only the Service ID:

• Format: ServiceID (without a resource suffix)

• Use resourceId: !sub '${Cybus::ServiceId}' in your endpoint configuration

Service-Level Tracking Limitations:

• Service tracking only begins reporting after the service has been enabled for the first time.

• Only reports whether the service is enabled or disabled.

• Service deviations (validation errors, resource-specific issues) are not reported by the Systemstate protocol when tracking at the service level.

• For detailed resource-level monitoring, use individual resource tracking instead.

Setting Up a Systemstate Endpoint

To set up a Systemstate endpoint:

1. Create a resource with type Cybus::Endpoint and specify the Systemstate protocol.

2. Define the component identifier that you want to monitor (see tracking types above).

Best practice: Rather than hardcoding the Service ID directly, use the parameter reference syntax !sub '${Cybus::ServiceId}' as shown in the example below. This improves flexibility and simplifies maintenance. For more details, see Inter-Service Referencing.

# Track individual resource
resourceEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Systemstate
    connection: !ref someConnection
    subscribe:
      resourceId: !sub '${Cybus::ServiceId}-someConnection'

# Track entire service
serviceEndpoint:
  type: Cybus::Endpoint
  properties:
    protocol: Systemstate
    connection: !ref someConnection
    subscribe:
      resourceId: !sub '${Cybus::ServiceId}'

Message Format Examples

Based on the example service commissioning file below, here are sample output messages from the protocol.

Your specific MQTT topics may vary, but the message payload structure shown here must be maintained - except when you have applied JSONata transformation rules.

When enabling an endpoint

{ "state": "enabling", "resourceId": "samplesystemstateservice-someEndpoint", "timestamp": 1621256032226 }

When an endpoint has been successfully enabled

{ "state": "enabled", "resourceId": "samplesystemstateservice-someEndpoint", "timestamp": 1621256032233 }

When a resource/service does not exist (read operation)

If you send a message to a topic with suffix req for a resource or service that does not exist, Systemstate will return an error response:

{ "state": "", "resourceId": "samplesystemstateservice-someEndpoint", "timestamp": 1770036468132, "error": "resource not found" }

Service Commissioning File Example

709B

systemstate-example.yml

Open

systemstate-example.yml

description: >
  Sample Systemstate service commissioning file

metadata:
  name: Sample Systemstate service
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

resources:
  someConnection:
    type: Cybus::Connection
    properties:
      protocol: Systemstate
      connection: {}

  someEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Systemstate
      connection: !ref someConnection
      subscribe:
        resourceId: !sub '${Cybus::ServiceId}-someConnection'

  anotherEndpoint:
    type: Cybus::Endpoint
    properties:
      protocol: Systemstate
      connection: !ref someConnection
      subscribe:
        resourceId: !sub '${Cybus::ServiceId}-someEndpoint'