Rename message field to text in Thin Edge JSON alarms payload

5 files changed, 44 insertions, 29 deletions

diff --git a/crates/core/c8y_smartrest/src/alarm.rs b/crates/core/c8y_smartrest/src/alarm.rs
index 630debe9..970dd991 100644
--- a/crates/core/c8y_smartrest/src/alarm.rs
+++ b/crates/core/c8y_smartrest/src/alarm.rs
@@ -21,7 +21,7 @@ pub fn serialize_alarm(alarm: ThinEdgeAlarm) -> Result<String, SmartRestSerializ
                 "{},{},\"{}\",{}",
                 smartrest_code,
                 alarm.name,
-                alarm_data.message.unwrap_or_default(),
+                alarm_data.text.unwrap_or_default(),
                 alarm_data.time.map_or_else(
                     || current_timestamp.format(&Rfc3339),
                     |timestamp| timestamp.format(&Rfc3339)
@@ -47,7 +47,7 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Critical,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I raised it".into()),
+                text: Some("I raised it".into()),
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         },
@@ -59,7 +59,7 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Major,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I raised it".into()),
+                text: Some("I raised it".into()),
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         },
@@ -71,7 +71,7 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Minor,
             data: Some(ThinEdgeAlarmData {
-                message: None,
+                text: None,
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         },
@@ -83,7 +83,7 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Warning,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I, raised, it".into()),
+                text: Some("I, raised, it".into()),
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         },
@@ -119,7 +119,7 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Warning,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I raised it".into()),
+                text: Some("I raised it".into()),
                 time: None,
             }),
         };
diff --git a/crates/core/tedge_mapper/src/c8y/tests.rs b/crates/core/tedge_mapper/src/c8y/tests.rs
index 04cf07cc..86c40a75 100644
--- a/crates/core/tedge_mapper/src/c8y/tests.rs
+++ b/crates/core/tedge_mapper/src/c8y/tests.rs
@@ -665,16 +665,16 @@ async fn check_c8y_threshold_packet_size() -> Result<(), anyhow::Error> {
     let mut converter = create_c8y_converter();
 
     let alarm_topic = "tedge/alarms/critical/temperature_alarm";
-    let big_message = create_packet(1024 * 20);
-    let alarm_payload = json!({ "message": big_message }).to_string();
+    let big_alarm_text = create_packet(1024 * 20);
+    let alarm_payload = json!({ "text": big_alarm_text }).to_string();
     let alarm_message = Message::new(&Topic::new_unchecked(alarm_topic), alarm_payload);
 
     assert_matches!(
         converter.try_convert(&alarm_message).await,
         Err(ConversionError::SizeThresholdExceeded {
             topic: _,
-            actual_size: 20494,
-            threshold: 16384
+            actual_size: _,
+            threshold: _
         })
     );
     Ok(())
diff --git a/crates/core/thin_edge_json/src/alarm.rs b/crates/core/thin_edge_json/src/alarm.rs
index 668a24b5..91167108 100644
--- a/crates/core/thin_edge_json/src/alarm.rs
+++ b/crates/core/thin_edge_json/src/alarm.rs
@@ -22,7 +22,7 @@ pub enum AlarmSeverity {
 /// In-memory representation of ThinEdge JSON alarm payload
 #[derive(Debug, Deserialize, PartialEq)]
 pub struct ThinEdgeAlarmData {
-    pub message: Option<String>,
+    pub text: Option<String>,
 
     #[serde(default)]
     #[serde(with = "clock::serde::rfc3339::option")]
@@ -103,14 +103,14 @@ mod tests {
     #[test_case(
         "tedge/alarms/critical/temperature_alarm",
         json!({
-            "message": "I raised it",
+            "text": "I raised it",
             "time": "2021-04-23T19:00:00+05:00",
         }),
         ThinEdgeAlarm {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Critical,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I raised it".into()),
+                text: Some("I raised it".into()),
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         };
@@ -119,13 +119,13 @@ mod tests {
     #[test_case(
         "tedge/alarms/major/temperature_alarm",
         json!({
-            "message": "I raised it",
+            "text": "I raised it",
         }),
         ThinEdgeAlarm {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Major,
             data: Some(ThinEdgeAlarmData {
-                message: Some("I raised it".into()),
+                text: Some("I raised it".into()),
                 time: None,
             }),
         };
@@ -140,11 +140,11 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Minor,
             data: Some(ThinEdgeAlarmData {
-                message: None,
+                text: None,
                 time: Some(datetime!(2021-04-23 19:00:00 +05:00)),
             }),
         };
-        "minor alarm parsing without message"
+        "minor alarm parsing without text"
     )]
     #[test_case(
         "tedge/alarms/warning/temperature_alarm",
@@ -153,11 +153,11 @@ mod tests {
             name: "temperature_alarm".into(),
             severity: AlarmSeverity::Warning,
             data: Some(ThinEdgeAlarmData {
-                message: None,
+                text: None,
                 time: None,
             }),
         };
-        "warning alarm parsing without message or timestamp"
+        "warning alarm parsing without text or timestamp"
     )]
     fn parse_thin_edge_alarm_json(
         alarm_topic: &str,
diff --git a/docs/src/tutorials/raise-alarm.md b/docs/src/tutorials/raise-alarm.md
index 3e1527b7..026edb33 100644
--- a/docs/src/tutorials/raise-alarm.md
+++ b/docs/src/tutorials/raise-alarm.md
@@ -24,7 +24,7 @@ The payload format must be as follows:
 
 ```json
 {
-    "message": "<message text>",
+    "text": "<alarm text>",
     "time": "<Timestamp in ISO-8601 format>"
 }
 ```
@@ -42,16 +42,16 @@ Topic:
 Payload:
 ```json
 {
-    "message": "Temperature is very high",
+    "text": "Temperature is very high",
     "time": "2021-01-01T05:30:45+00:00"
 }
 ```
 
-> Note: Both the `message` field and the `time` field are optional.
-When a `message` is not provided, it is assumed to be empty.
+> Note: Both the `text` field and the `time` field are optional.
+When a `text` is not provided, it is assumed to be empty.
 When `time` is not provided, thin-edge.io will use the current system time as the `time` of the alarm.
 When you want to skip both fields, use an empty json fragment `{}` as the payload to indicate the same.
-An empty message can't be used for the same as empty messages are used to clear alarms, which is discussed in the next section.
+An empty message can't be used for the same, as empty messages are used to clear alarms, which is discussed in the next section.
 
 The `<severity>` value in the MQTT topic can only be one of the following values:
 
@@ -79,4 +79,19 @@ The mapping of thin-edge alarms data to its respective cloud-native representati
 For example, if the device is connected to Cumulocity IoT cloud platform, the Cumulocity cloud mapper process will translate the thin-edge alarm JSON data to its equivalent Cumulocity SmartREST representation.
 
 > Warning: As of now, alarm data mapping is supported only on Cumulocity IoT cloud platform.
+
+### Cumulocity cloud data mapping
+
+The Cumulocity mapper will convert Thin Edge JSON alarm into Cumulocity SmartREST messages and send it to Cumulocity via MQTT.
+
+For example the `temperature_high` alarm with `critical` severity described in the earlier sections will be converted to the following Cumulocity SmartREST message:
+
+```csv
+301,temperature_high,"Temperature is very high",2021-01-01T05:30:45+00:00
+```
+
+... and is published to `c8y/s/us` topic which will get forwarded to the connected Cumulocity cloud instance.
+
+Find more information about SmartREST representations for alarms in Cumulocity [here](https://cumulocity.com/guides/10.11.0/reference/smartrest-two/#alarm-templates)
+
 Find more information about alarms data model in Cumulocity [here](https://cumulocity.com/guides/concepts/domain-model/#events)
diff --git a/tests/PySys/tedge_mapper_c8y/tedge_mapper_c8y_alarms/run.py b/tests/PySys/tedge_mapper_c8y/tedge_mapper_c8y_alarms/run.py
index fd3c5d0b..337f5d32 100644
--- a/tests/PySys/tedge_mapper_c8y/tedge_mapper_c8y_alarms/run.py
+++ b/tests/PySys/tedge_mapper_c8y/tedge_mapper_c8y_alarms/run.py
@@ -23,13 +23,13 @@ class TedgeMapperC8yAlarm(EnvironmentC8y):
 
         # Pysys seems to print and record the environment it will also print passwords in the env
         # Solution: only inject the variables we really need
-        environ={ 'HOME':os.environ.get('HOME')}
+        environ = {'HOME': os.environ.get('HOME')}
 
         self.startProcess(
             command=self.tedge,
             arguments=["mqtt", "pub", "-r",
                        "tedge/alarms/warning/temperature_high",
-                       '{"message":"temperature is high", "time":"2021-12-15T15:22:06.464247777+05:30"}'],
+                       '{"text":"temperature is high", "time":"2021-12-15T15:22:06.464247777+05:30"}'],
             environs=environ
         )
 
@@ -38,7 +38,7 @@ class TedgeMapperC8yAlarm(EnvironmentC8y):
             command=self.tedge,
             arguments=["mqtt", "pub", "-r",
                        "tedge/alarms/major/temperature_very_high",
-                       '{"message":"temperature is very high"}'],
+                       '{"text":"temperature is very high"}'],
             environs=environ
         )
 
@@ -47,7 +47,7 @@ class TedgeMapperC8yAlarm(EnvironmentC8y):
             command=self.tedge,
             arguments=["mqtt", "pub", "-r",
                        "tedge/alarms/critical/temperature_dangerous",
-                       '{"message":"temperature is dangerously high"}'],
+                       '{"text":"temperature is dangerously high"}'],
             environs=environ
         )
 
@@ -56,7 +56,7 @@ class TedgeMapperC8yAlarm(EnvironmentC8y):
             command=self.tedge,
             arguments=["mqtt", "pub", "-r",
                        "tedge/alarms/minor/temperature_low",
-                       '{"message":"temperature low"}'],
+                       '{"text":"temperature low"}'],
             environs=environ
         )