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.

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.

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 by combining both:

   • Service ID

   • Resource ID

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

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.

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

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 }

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'