Is your feature improvement request related to a problem? Please describe.
The custom operation is currently limited to SmartREST input and main device. Since we have workflow feature, mapper can focus on generating a thin-edge command, and move the actual execution of the operation to tedge-agent.

Describe the solution you'd like
Mapper provides a way for users how to map the c8y JSON to thin-edge JSON.

Let's use this custom operation com_cumulocity_model_WebCamDevice as an example.

C8Y JSON input

All operations including custom operations will be delivered to the JSON over MQTT topic c8y/devicecontrol/notifications.

{
   "delivery":{
      "log":[
         
      ],
      "time":"2024-09-02T19:56:01.342Z",
      "status":"PENDING"
   },
   "agentId":"201802315",
   "creationTime":"2024-09-02T19:56:01.313Z",
   "deviceId":"201802315",
   "id":"1800380",
   "status":"PENDING",
   "com_cumulocity_model_WebCamDevice":{
      "name":"take picture",
      "parameters":{
         "duration":"5s",
         "quality":"HD"
      }
   },
   "description":"WebCam picture",
   "externalSource":{
      "externalId":"TST_haul_searing_set",
      "type":"c8y_Serial"
   }
}

Drop 1

File: /etc/tedge/operations/c8y/com_cumulocity_model_WebCamDevice (for main device)

The mapper spawns a child process (= same mechanism as the existing custom operation handler) from the JSON over MQTT input.
The filename is used for declaring supported operation. The keyon_fragment is used to check if the mapping file matches the input payload. If topic is not provided, the device control topic is used by default unless on_message is defined. skip_status_update is optional. If true, mapper doesn't send operation status update messages (501-503/504-506).

[exec]
topic = "c8y/devicecontrol/notifications"
on_fragment = "com_cumulocity_model_WebCamDevice"
command = "/usr/bin/do_something.sh ${.payload.com_cumulocity_model_WebCamDevice.parameters.duration}"
skip_status_update = true

FYI: existing custom operation handler definition

[exec]
topic = "c8y/s/ds"
on_message = "511"
command = "/usr/bin/c8y-command"

Drop 2

Mapping definition by user

The mapper converts the incoming JSON over MQTT message to thin-edge command message as per the definition file.

User is supposed to create a master custom operation definition file with .template extension. e.g. /etc/tedge/operations/c8y/com_cumulocity_model_WebCamDevice.template

[exec]
topic = "c8y/devicecontrol/notifications"
on_fragment = "com_cumulocity_model_WebCamDevice"

[exec.workflow]
operation = "take_picture"
input = "${.payload.com_cumulocity_model_WebCamDevice.parameters}"

To indicate that devices are supporting the operation, the device must publish a command capability message.

tedge mqtt pub -r 'te/device/<name>///cmd/take_picture' '{}'

On receiving, mapper creates a simlink in /etc/tedge/operations/c8y/com_cumulocity_model_WebCamDevice (main), /etc/tedge/operations/c8y/<external_id>/com_cumulocity_model_WebCamDevice (child/service) to the master file.

Mapper detects the change in the /etc/tedge/operations/c8y directory except .template file. When the change is detected, 114 (supported operation) message must be sent to c8y.

Convert to thin-edge command

Topic: te/device/<name>///cmd/take_picture/c8y-mapper-1800380

{
      "status": "init", // Must be added by mapper
      "duration":"5s",
      "quality":"HD"
}

Status update to C8Y

Topic: te/device/<name>///cmd/take_picture/c8y-mapper-1800380

{
      "status": "executing",
      "duration":"5s",
      "quality":"HD"
}

Mapper converts it to SmartREST 504 or 501 for executing status.

504,1800380 
501,com_cumulocity_model_WebCamDevice

The same pattern is applied to successful/failed message, 502/504, and 503/506.

Describe alternatives you've considered
Another option is using command metadata message to define mapping.

tedge mqtt pub -r te/device/<name>///cmd/take_picture`{
   "exec": {
      "topic": "c8y/devicecontrol/notifications"
      "on_fragment": "com_cumulocity_model_WebCamDevice"
      "command_name": "take_picture" # KEY NAME TBD, as "command" is already taken for executable path
      "command_payload": "${.payload.com_cumulocity_model_WebCamDevice.parameters}"
    }
}`

Additional context
The original roadmap ticket is here.