Manage the configuration repository

Upload a configuration file, create a configuration snapshot for it in the configuration repository, announce the configuration types of a device, list the snapshots, and delete a snapshot with its file.

The configuration repository stores configuration snapshots: configuration files that you can install on devices. Each snapshot is a managed object of the type c8y_ConfigurationDump. Its url points to the configuration file, usually a file that is stored in the inventory of your tenant.

A configuration snapshot has the following properties:

• name: The name of the snapshot. Mandatory.
• type: Always c8y_ConfigurationDump. Mandatory.
• url: The URL of the configuration file. Mandatory.
• description: A description of the snapshot. Optional.
• configurationType: The configuration type, for devices with typed file-based configuration. Omit it for devices with legacy file-based configuration.
• deviceType: The device type that the snapshot applies to. Omit it to make the snapshot available for all device types.

Devices with legacy file-based configuration only accept files that are stored in Cumulocity. External URLs only work with devices that support typed file-based configuration. To install a snapshot on a device, see Apply and retrieve device configuration.

The examples use <snapshot_id> for the ID of a configuration snapshot, <binary_id> for the ID of an uploaded file, and <device_id> for the ID of a device.

To upload the configuration file

If the configuration file is already available at a URL, skip this step and use that URL as <file_url>.

Send an Upload a file request as multipart/form-data with two parts. The part object contains the name and the media type of the file, the part file contains the file:

POST /inventory/binaries
Content-Type: multipart/form-data; boundary=boundary
Accept: application/json

--boundary
Content-Disposition: form-data; name="object"

{ "name": "agent.conf", "type": "text/plain" }
--boundary
Content-Disposition: form-data; name="file"; filename="agent.conf"
Content-Type: text/plain

c8y.url.http=https://management.cumulocity.com
c8y.url.mqtt=mqtt.cumulocity.com
--boundary--

The platform returns HTTP 201 and a managed object with the fragment c8y_IsBinary. Note its self URL as <file_url> and its id as <binary_id>.

To create a configuration snapshot

Send a Create one or multiple managed objects request:

POST /inventory/managedObjects
Content-Type: application/json
Accept: application/json

{
  "name": "Agent configuration",
  "description": "Default agent configuration for Linux gateways",
  "type": "c8y_ConfigurationDump",
  "url": "<file_url>",
  "configurationType": "agent_conf",
  "deviceType": "c8y_Linux"
}

To make the snapshot visible to all users of the tenant, regardless of their inventory permissions, also add the fragment "c8y_Global": {}. See Globally accessible objects.

The platform returns HTTP 201 and the snapshot with its id. Note the id as <snapshot_id>.

If the request fails after you uploaded a file for the snapshot, delete the file, see To delete a configuration snapshot.

To announce the configuration types of a device

A device with typed file-based configuration lists its configuration types in the c8y_SupportedConfigurations fragment of its managed object. Usually, the device agent sets this fragment. Cumulocity does not validate the types. They are plain strings, and the device agent assigns them to its configuration files.

To set the fragment, send an Update a specific managed object request with all types of the device:

PUT /inventory/managedObjects/<device_id>
Content-Type: application/json
Accept: application/json

{
  "c8y_SupportedConfigurations": ["agent_conf", "ssh_conf"]
}

The platform returns HTTP 200 and the device with the new c8y_SupportedConfigurations array. The request replaces the whole fragment and does not change other fragments. If the platform returns HTTP 404, the device does not exist.

To list the configuration snapshots

Send a Retrieve all managed objects request with a query for the type:

GET /inventory/managedObjects?query=$filter=(type eq 'c8y_ConfigurationDump')&pageSize=100&withTotalPages=true

The example shows the query parameter unencoded for readability. URL-encode its value when you send the request, for example, replace each space with %20.

The managedObjects array of the response contains the snapshots with their id, name, url, configurationType, and deviceType. The statistics.totalPages property shows the number of pages. To read the next page, add currentPage=2, and so on.

To delete a configuration snapshot

1. Send a Remove a specific managed object request:

   DELETE /inventory/managedObjects/<snapshot_id>
   

   The platform returns HTTP 204.

2. If you uploaded the file for this snapshot, send a Remove a stored file request:

   DELETE /inventory/binaries/<binary_id>
   

   The platform returns HTTP 204 and deletes the file together with its managed object.