--- name: cumulocity-manage-configuration-repository description: "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. Use when the user wants to add, list, or delete configuration files in the configuration repository, or announce the configuration types of a device." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage the configuration repository Source: https://cumulocity.com/docs/skills/device-management/manage-configuration-repository/ Sector: Skills, Device management & connectivity Release: Latest Description: 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. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) 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](https://cumulocity.com/docs/skills/device-management/apply-device-configuration/). > **Requirements:** > ROLES & PERMISSIONS: > > * To upload files and to create, update, and delete managed objects: ROLE_INVENTORY_ADMIN > * To list the snapshots: ROLE_INVENTORY_READ The examples use `` for the ID of a configuration snapshot, `` for the ID of an uploaded file, and `` for the ID of a device. ### To upload the configuration file {#to-upload-the-configuration-file} If the configuration file is already available at a URL, skip this step and use that URL as ``. Send an [Upload a file](https://cumulocity.com/api/core/#operation/postBinariesCollectionResource) 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: ```http 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 `` and its `id` as ``. ### To create a configuration snapshot {#to-create-a-configuration-snapshot} Send a [Create one or multiple managed objects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource) request: ```http POST /inventory/managedObjects Content-Type: application/json Accept: application/json { "name": "Agent configuration", "description": "Default agent configuration for Linux gateways", "type": "c8y_ConfigurationDump", "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](https://cumulocity.com/docs/concepts/security/#globally-accessible-objects). The platform returns HTTP 201 and the snapshot with its `id`. Note the `id` as ``. If the request fails after you uploaded a file for the snapshot, delete the file, see [To delete a configuration snapshot](https://cumulocity.com/docs/skills/device-management/manage-configuration-repository/#to-delete-a-configuration-snapshot). ### To announce the configuration types of a device {#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](https://cumulocity.com/api/core/#operation/putManagedObjectResource) request with all types of the device: ```http PUT /inventory/managedObjects/ 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 {#to-list-the-configuration-snapshots} Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request with a query for the type: ```http 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 {#to-delete-a-configuration-snapshot} 1. Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request: ```http DELETE /inventory/managedObjects/ ``` The platform returns HTTP 204. 2. If you uploaded the file for this snapshot, send a [Remove a stored file](https://cumulocity.com/api/core/#operation/deleteBinariesResource) request: ```http DELETE /inventory/binaries/ ``` The platform returns HTTP 204 and deletes the file together with its managed object. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /inventory/binaries](https://cumulocity.com/api/core/#operation/postBinariesCollectionResource): Upload a file - [POST /inventory/managedObjects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource): Create one or multiple managed objects - [PUT /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/putManagedObjectResource): Update a specific managed object - [GET /inventory/managedObjects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource): Retrieve all managed objects - [DELETE /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource): Remove a specific managed object - [DELETE /inventory/binaries/{id}](https://cumulocity.com/api/core/#operation/deleteBinariesResource): Remove a stored file ## Linked from the documentation - [Managing device data > Managing configurations](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-configurations)