Is your documentation request related to a problem? Please describe.

The current documentation clearly explains how to send a simple, flat JSON payload which is then mapped into a series of top-level fragments in a Cumulocity measurement.

However, it is unclear how to model more complex data that adheres to Cumulocity's best practices, where:

1. All related time-series values are grouped under a single, specific fragment.
2. Additional non-time-series metadata (like strings or booleans) is stored in other, separate custom fragments within the same measurement object.

The Cumulocity REST API supports this structure, but I cannot find documentation that explains how to construct a thin-edge.io MQTT payload to achieve this result through the mapper.

Describe the improvement you'd like

The documentation should be updated to clarify if and how a single thin-edge.io MQTT message can create a Cumulocity measurement containing multiple, distinct top-level fragments, where one fragment contains all the time-series data and other fragments contain arbitrary metadata.

Specifically, the documentation should provide an example that shows how to create the following target measurement structure in Cumulocity.

Target Cumulocity Measurement Structure:

{
  "type": "machine_energy_measurement",
  "time": "...",
  "source": { "...": "..." },

  "robot_mech_energy": {
     "accumulated_energy": { "value": 0.1, "unit": "kWh" },
     "ROB_1_axis_1_energy": { "value": 0.1, "unit": "kWh" },
     "ROB_1_axis_2_energy": { "value": 0.2, "unit": "kWh" },
     "ROB_1_axis_3_energy": { "value": 0.3, "unit": "kWh" },
     "ROB_1_axis_4_energy": { "value": 0.4, "unit": "kWh" },
     "ROB_1_axis_5_energy": { "value": 0.5, "unit": "kWh" },
     "ROB_1_axis_6_energy": { "value": 0.6, "unit": "kWh" },
     "ROB_2_axis_1_energy": { "value": 0.1, "unit": "kWh" },
     "ROB_2_axis_2_energy": { "value": 0.2, "unit": "kWh" },
     "ROB_2_axis_3_energy": { "value": 0.3, "unit": "kWh" },
     "ROB_2_axis_4_energy": { "value": 0.4, "unit": "kWh" },
     "ROB_2_axis_5_energy": { "value": 0.5, "unit": "kWh" },
     "ROB_2_axis_6_energy": { "value": 0.6, "unit": "kWh" }
  },

  "measurement_context": {
    "status": "nominal",
    "cycle_id": "cycle-98765"
  }
}

If this is possible, the documentation should provide the corresponding thin-edge.io MQTT payload needed. If this is not supported, this limitation should be explicitly stated.

Additional context

The key challenge is understanding how the c8y-mapper handles a nested JSON payload. For the example above, it's not clear what the input payload should be. Would a payload like the one below work?

Hypothetical thin-edge.io MQTT Payload:

{
  "robot_mech_energy": {
     "accumulated_energy": 0.1,
     "ROB_1_axis_1_energy": 0.1,
     "ROB_1_axis_2_energy": 0.2,
     "ROB_1_axis_3_energy": 0.3,
     "ROB_1_axis_4_energy": 0.4,
     "ROB_1_axis_5_energy": 0.5,
     "ROB_1_axis_6_energy": 0.6,
     "ROB_2_axis_1_energy": 0.1,
     "ROB_2_axis_2_energy": 0.2,
     "ROB_2_axis_3_energy": 0.3,
     "ROB_2_axis_4_energy": 0.4,
     "ROB_2_axis_5_energy": 0.5,
     "ROB_2_axis_6_energy": 0.6
  },
  "measurement_context": {
    "status": "nominal",
    "cycle_id": "cycle-98765"
  }
}

Clarifying how the mapper processes such a structure - specifically how it differentiates between a fragment intended to hold time-series data versus a fragment for general-purpose metadata - would be extremely valuable for modeling complex assets.

Relevant documentation page: MQTT API