--- name: cumulocity-manage-software-repository description: "Create a software in the software repository, upload software files, add versions, list the software that a device can install, and delete a software with all its versions. Use when the user wants to add software or software versions to the software repository, list them, or delete them." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Manage the software repository Source: https://cumulocity.com/docs/skills/device-management/manage-software-repository/ Sector: Skills, Device management & connectivity Release: Latest Description: Create a software in the software repository, upload software files, add versions, list the software that a device can install, and delete a software with all its versions. ## 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 software repository collects the software packages that you install on devices. It is stored in the inventory: * Each software is a managed object of the type `c8y_Software` with a `name` and a `description`. * Each version of a software is a child addition of the software, of the type `c8y_SoftwareBinary`. Its `c8y_Software` fragment contains the `version` and the `url` of the software file. A software can have the following restrictions: * **Device type filter**: With `c8y_Filter.type`, the software is only available for devices of this managed object type. * **Software type**: The `softwareType` property organizes the software, for example by package manager, such as `apt` or `container`. A device that lists software types in its `c8y_SupportedSoftwareTypes` fragment can only install software of these types. To install a software version on a device, see [Install software on a device](https://cumulocity.com/docs/skills/device-management/install-device-software/). > **Requirements:** > ROLES & PERMISSIONS: > > * To create and delete software, versions, and files: ROLE_INVENTORY_ADMIN > * To list software and versions: ROLE_INVENTORY_READ The examples use `` for the ID of a software, `` for a version identifier such as `1.0.0`, `` for a device type, and `` for a software type. ### To create a software {#to-create-a-software} 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": "myapp", "description": "Telemetry collector for field gateways", "type": "c8y_Software", "softwareType": "", "c8y_Filter": { "type": "" } } ``` Omit `c8y_Filter` to make the software available for all device types. Omit `softwareType` if the software has no software type. To make the software visible to all users of the tenant, regardless of their inventory permissions, add the fragment `"c8y_Global": {}` to the software and to each version. The visibility does not extend to child objects. See [Globally accessible objects](https://cumulocity.com/docs/concepts/security/#globally-accessible-objects). The platform returns HTTP 201 and the software with its `id`. Note the `id` as ``. ### To upload a software file {#to-upload-a-software-file} Each version refers to its software file by URL. You have the following options: * Use the URL of a file that is already hosted elsewhere. * Upload the file to Cumulocity and use its URL. * Use an empty string if the device resolves the file itself, for example with a package manager. If the device cannot resolve it, the software operation fails. To upload the file, send an [Upload a file](https://cumulocity.com/api/core/#operation/postBinariesCollectionResource) request as `multipart/form-data`. 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": "myapp-1.0.0.deb", "type": "application/octet-stream" } --boundary Content-Disposition: form-data; name="file"; filename="myapp-1.0.0.deb" Content-Type: application/octet-stream --boundary-- ``` The platform returns HTTP 201 and a managed object with the fragment `c8y_IsBinary`. Note its `self` URL as ``. ### To add a version {#to-add-a-version} Send an [Assign a managed object as child addition](https://cumulocity.com/api/core/#operation/postManagedObjectChildAdditionsResource) request with the content type `application/vnd.com.nsn.cumulocity.managedobject+json`: ```http POST /inventory/managedObjects//childAdditions Content-Type: application/vnd.com.nsn.cumulocity.managedobject+json Accept: application/json { "type": "c8y_SoftwareBinary", "c8y_Software": { "version": "", "url": "" } } ``` With this content type, the platform creates the version and assigns it to the software in one request. It returns HTTP 201 and the version with its `id`. If the platform returns HTTP 404, the software `` does not exist. ### To list software {#to-list-software} The examples in this section show the `query` parameter unencoded for readability. URL-encode its value when you send the request, for example, replace each space with `%20`. To list all software sorted by name, send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request: ```http GET /inventory/managedObjects?query=$filter=(type eq 'c8y_Software') $orderby=name asc&pageSize=2000&withTotalPages=true ``` The `managedObjects` array of the response contains the software. Without `pageSize`, the platform returns 5 objects per page. The `statistics.totalPages` property shows the number of pages. ### To list the software that a device can install {#to-list-the-software-that-a-device-can-install} A software matches a device if both of the following conditions apply: * Its `c8y_Filter.type` equals the `type` of the device, is empty, or is missing. * If the device has a `c8y_SupportedSoftwareTypes` fragment, the `softwareType` of the software is one of its values. Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request with both conditions: ```http GET /inventory/managedObjects?query=$filter=(type eq 'c8y_Software' and (c8y_Filter.type eq '' or c8y_Filter.type eq '' or not(has(c8y_Filter.type))) and (softwareType eq '')) $orderby=name asc&pageSize=2000 ``` If the device supports several software types, add one `softwareType eq` condition for each type and join them with `or`. If the device has no `c8y_SupportedSoftwareTypes` fragment, omit the software type condition. Put the type condition into the query. If the request has a `query` parameter, the platform ignores a separate `type` parameter. ### To list the versions of a software {#to-list-the-versions-of-a-software} Send a [Retrieve all managed objects](https://cumulocity.com/api/core/#operation/getManagedObjectCollectionResource) request for the children of the software, newest first: ```http GET /inventory/managedObjects?query=$filter=(bygroupid()) $orderby=creationTime.date desc&pageSize=2000&withTotalPages=true ``` Each entry of the `managedObjects` array contains the `id` of the version and its `c8y_Software.version`. If the array is empty, the software has no versions yet. ### To delete a software {#to-delete-a-software} Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request with `forceCascade=true`: ```http DELETE /inventory/managedObjects/?forceCascade=true ``` With `forceCascade=true`, the platform deletes the software together with all its versions. It returns HTTP 204. If the deletion takes longer than 30 seconds, the platform returns HTTP 202 and continues in the background. If the platform returns HTTP 404, the software does not exist. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [POST /inventory/managedObjects](https://cumulocity.com/api/core/#operation/postManagedObjectCollectionResource): Create one or multiple managed objects - [POST /inventory/binaries](https://cumulocity.com/api/core/#operation/postBinariesCollectionResource): Upload a file - [POST /inventory/managedObjects/{id}/childAdditions](https://cumulocity.com/api/core/#operation/postManagedObjectChildAdditionsResource): Assign a managed object as child addition - [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 ## Linked from the documentation - [Managing device data > Managing software](https://cumulocity.com/docs/device-management-application/managing-device-data/#managing-software)