Skip to main content
Version: Next

Service Commands

A Cumulocity operator can perform operations on a service of a device: start it, stop it, restart it, or run any other action that service supports. This is the Cumulocity feature documented under service commands.

The mapping details are described in the Cumulocity mapper reference.

Declaring the supported service commands​

A service is first registered with its service type in the type field. The service type selects whether the init system or a service plugin runs the actions.

tedge mqtt pub -r 'te/device/main/service/collectd' '{
  "@type": "service",
  "@parent": "device/main//",
  "type": "service",
  "name": "collectd"
}'

If auto-registration is enabled, a service that is not registered yet is registered with the default type service when it declares its first action.

A service declares each action that it supports by publishing a retained message to its cmd/<action> topic, one per action.

tedge mqtt pub -r 'te/device/main/service/collectd/cmd/restart' '{}'

Each declared action is added, uppercased, to the c8y_SupportedServiceCommands fragment of the service managed object. A custom action is declared the same way. A service declaring cmd/pause gets PAUSE in the list.

An action whose name breaks the action name rule is not declared to Cumulocity at all, and the mapper logs why.

Creating a service command operation​

Create a service command operation from Services > service name > Commands.

https://example.cumulocity.com/apps/devicemanagement/index.html#/service/12345/commands

Cumulocity service commands

The operation is sent to the device, where tedge-agent runs the workflow of that action on the service. The operation moves to SUCCESSFUL or FAILED when the workflow ends.

Rejected operations​

An operation is failed straight away, with no thin-edge.io command published, when:

  • the target service cannot be resolved.
  • the action is not one the service has declared. The action name is compared case-insensitively, so RESTART matches a declared restart.
  • the operation's serviceName or serviceType breaks the rule for that argument.

Removing an action​

An action can be removed by publishing a retained empty message to its capability topic.

tedge mqtt pub -r 'te/device/main/service/collectd/cmd/restart' ''

The action is removed from the c8y_SupportedServiceCommands fragment of the service managed object.

Disabling service commands​

To disable service commands from Cumulocity, set c8y.enable.service_commands to false and restart the mapper.

tedge config set c8y.enable.service_commands false
sudo systemctl restart tedge-mapper-c8y

The mapper then ignores the cmd/<action> capabilities of the services and the c8y_ServiceCommand operations.

note

Disabling service commands keeps what the mapper created while they were enabled: the c8y_ServiceCommand operation file under /etc/tedge/operations/c8y/<service-external-id>, and the c8y_SupportedServiceCommands fragment of the service managed object.