Align software management feature to the Cumulocity advanced software management API

[reubenmiller]

Is your feature improvement request related to a problem? Please describe.

Since 10.14, Cumulocity IoT introduced new API to manage the software list for devices.

thin-edge.io should use this API instead of using the legacy API which just sends a REST PUT to the inventory management API.

Describe the solution you'd like

Usage of the advanced software requires are the following parts to be implemented

1. Send the list of supported software types via MQTT (using JSON over MQTT, as unfortunately the in-built smart rest template 143 was only added around 10.17/10.18)

   Below is an example of the payload that needs to be sent to the JSON over MQTT topic: inventory/managedObjects/update/{xid} (same payload for both parent and child device)

   {"c8y_SupportedSoftwareTypes":["apt","nodered"]}
   

2. Send the software list to the Advanced Software Management API, see reference

Describe alternatives you've considered

Sending the software list over MQTT might exceed the maximum MQTT message payload size for large software lists.

Additional context

[rina23q]

I confirmed that declaring supported software types can be done via JSON over MQTT with the inventory endpoint. However, to update the list of installed software, we have to use one of below.

• HTTP REST endpoint: POST to {{url}}/service/advanced-software-mgmt/software?deviceId={{deviceId}}
• MQTT SmartREST static template: 140 (POST), 141 (PUT)

@reubenmiller suggested that we will use SmartREST instead of HTTP REST because we have a way to avoid MQTT threshold issue by combining 140 and 141 for big messages. The scenario is below:

a. If message payload is smaller than the MQTT size threshold, c8y-mapper publishes only one 140 SmartREST message. This template is corresponding to the REST POST action, which means the message will overwrite the old contents (= software list).

b. If message payload exceeds the MQTT size threshold, c8y-mapper firstly publishes one 140 message. Then, oversized contents are sent with 141 message(s). The 141 template is corresponding to the REST PUT action, which means the content will be added to the old contents.

[rina23q]

Resolved by https://github.com/thin-edge/thin-edge.io/pull/2771.

In addition to the original decision, we introduced two tedge config params.

1. c8y.software_management.api To switch legacy software management (= sending list via HTTP) and advanced one (= sending list via SmartREST). By default, it is set to legacy. To enhance the detection, the ticket #2778 is created.
2. c8y.software_management.with_types If mapper publishes c8y_SupportedSoftwareTypes to the inventory or not. If the type is set in its managed object, c8y stop using c8y_SoftwareList fragment to look up the installed software list. By default, it is set to false so that we can still use c8y_SoftwareList fragment for testing and so on.

Why? For 1), we realized a usecase, where the tenant version is > 10.14 but it doesn't subscribe to the Advanced-software-mgmt microservice. So, we decided NOT to use the advanced endpoint by default.

In short, #2771 didn't change any c8y-mapper behaviour by default unless user changes tedge config. If 1) is enabled, c8y-mapper starts sending software list with MQTT, using SmartREST. If the list is long, first sending 140 message, then one or more 141 messages to append the list. If 2) is enabled, c8y-mapper sends c8y_SupportedSoftwareTypes to the inventory endpoint via JSON over MQTT.

[gligorisaev]

QA has thoroughly checked the feature and here are the results:

• [x] Test for ticket exists in the test suite.
• tests/RobotFramework/tests/cumulocity/software_management/software.robot
• tests/RobotFramework/tests/tedge/call_tedge_config_list.robot
• [x] QA has tested the function and it's functioning according

[rina23q]

The new URL of the c8y guide for advanced software management: https://cumulocity.com/docs/device-integration/fragment-library/#software