--- name: cumulocity-replace-device description: "Replace the hardware of a device and keep its history by moving the external IDs and hardware information of a replacement device to the original device, deleting the replacement device, and recording the replacement. Use when the user wants to replace the hardware of a device and keep its history." compatibility: "Requires network access to a Cumulocity tenant and the C8Y_BASEURL, C8Y_TENANT, C8Y_USER, and C8Y_PASSWORD environment variables." --- # Replace a device Source: https://cumulocity.com/docs/skills/device-management/replace-device/ Sector: Skills, Device management & connectivity Release: Latest Description: Replace the hardware of a device and keep its history by moving the external IDs and hardware information of a replacement device to the original device, deleting the replacement device, and recording the replacement. ## Before you start Use these skills first: - `cumulocity-authentication` skill: [Authenticate REST API requests](https://cumulocity.com/docs/skills/platform-administration/authentication/index.md) When the hardware of a device breaks, you replace it and keep the data that the old hardware recorded. First, register the new hardware like any other device, see [Register a device](https://cumulocity.com/docs/skills/device-management/register-device/). The platform now has two managed objects: * The original device keeps its ID and all its data. It receives the external IDs, the hardware information, and the owner of the replacement device. * The replacement device is the managed object that the new hardware created. You delete it after you moved its identity to the original device. After the replacement, the new hardware sends its data to the original device. The Device Management application offers the same procedure as a wizard, see [To replace a device](https://cumulocity.com/docs/device-management-application/viewing-all-devices/#to-replace-a-device). The wizard also deletes the device user of the original device if this user owns no other managed objects. This skill does not delete users. For the steps in the context of a device integration, see [Replacing a physical device](https://cumulocity.com/docs/device-integration/device-integration-rest/#replacing-a-physical-device). > **Caution:** > The replacement deletes the replacement device and all data generated for it so far. > **Requirements:** > ROLES & PERMISSIONS: > > * To read the devices: ROLE_INVENTORY_READ > * To update and delete the devices: ROLE_INVENTORY_ADMIN > * To read external IDs: ROLE_IDENTITY_READ > * To move external IDs: ROLE_IDENTITY_ADMIN > * To create the event: ROLE_EVENT_ADMIN > * To create the audit record: ROLE_AUDIT_ADMIN The examples use `` for the ID of the original device and `` for the ID of the replacement device. ### To check both devices {#to-check-both-devices} Send a [Retrieve a specific managed object](https://cumulocity.com/api/core/#operation/getManagedObjectResource) request for the original device, and the same request with `` for the replacement device: ```http GET /inventory/managedObjects/ ``` The platform returns HTTP 200 for both requests. Check the following: * Both managed objects contain the fragment `c8y_IsDevice`. * `` and `` are different. * The replacement device has an `owner`. Note it as ``. Also note the `c8y_Hardware` fragment of the replacement device exactly as returned, if it has one. You need it later, and it is gone when you delete the replacement device. If the platform returns HTTP 404, the device does not exist. ### To record the current state {#to-record-the-current-state} 1. Send a [Retrieve all external IDs of a specific managed object](https://cumulocity.com/api/core/#operation/getExternalIDCollectionResource) request for the original device, and the same request with `` for the replacement device: ```http GET /identity/globalIds//externalIds ``` The `externalIds` array of each response lists the external IDs of the device, each with `externalId` and `type`. Note both lists. Either list can be empty. 2. Send a [Retrieve the current user](https://cumulocity.com/api/core/#operation/getCurrentUserResource) request: ```http GET /user/currentUser ``` Note the `id` of the user as ``. 3. Note the current time in UTC in ISO 8601 format as ``, for example `2026-10-14T09:30:00.000Z`. Record the external IDs only once, before you move them. Afterwards, the original device also lists the external IDs of the replacement device. ### To move the external IDs to the original device {#to-move-the-external-ids-to-the-original-device} A delete request removes an external ID from whichever device holds it. Therefore, check the holder of each external ID before you delete it. For each external ID of the replacement device, with `` and `` from the list: 1. Send a [Retrieve a specific external ID](https://cumulocity.com/api/core/#operation/getExternalIDResource) request: ```http GET /identity/externalIds// ``` Continue only if `managedObject.id` in the response is ``. If another device holds the external ID, do not delete or move it. 2. Send a [Remove a specific external ID](https://cumulocity.com/api/core/#operation/deleteExternalIDResource) request: ```http DELETE /identity/externalIds// ``` The platform returns HTTP 204. HTTP 404 means that the external ID is already removed. 3. Send a [Create an external ID](https://cumulocity.com/api/core/#operation/postExternalIDCollectionResource) request for the original device: ```http POST /identity/globalIds//externalIds Content-Type: application/json Accept: application/json { "externalId": "", "type": "" } ``` The platform returns HTTP 201 and the external ID. If it returns HTTP 409, a different managed object holds the external ID. Look up the holder with the request of step 1 and stop. Do not delete that external ID. Then remove the previous external IDs of the original device. For each external ID in the list of the original device that the replacement device did not have, check with the request of step 1 that `managedObject.id` is ``, and delete it with the request of step 2. ### To update the original device {#to-update-the-original-device} Send an [Update a specific managed object](https://cumulocity.com/api/core/#operation/putManagedObjectResource) request: ```http PUT /inventory/managedObjects/ Content-Type: application/json Accept: application/json { "owner": "", "c8y_LastReplacement": { "time": "", "user": "", "previousExternalIds": [ { "externalId": "", "type": "c8y_Serial" } ] }, "c8y_Hardware": { "serialNumber": "", "model": "", "revision": "" } } ``` The request body has the following properties: * `owner`: The owner of the replacement device. * `c8y_LastReplacement`: The record of this replacement. `previousExternalIds` lists the external IDs that the original device had before the replacement, or is an empty array if it had none. * `c8y_Hardware`: The `c8y_Hardware` fragment of the replacement device, exactly as you noted it. If the replacement device has no `c8y_Hardware`, leave the property out. Do not guess the values. The update is partial. All other fragments of the original device stay unchanged. The platform returns HTTP 200 and the device with `c8y_LastReplacement`. ### To delete the replacement device {#to-delete-the-replacement-device} Send a [Remove a specific managed object](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource) request: ```http DELETE /inventory/managedObjects/ ``` Do not add the parameter `withDeviceUser=true`. The new hardware still needs its device user. The platform returns HTTP 204 when it deleted the managed object within 30 seconds. HTTP 202 means that the deletion continues in the background. To check that the deletion is complete, send `GET /inventory/managedObjects/` until it returns HTTP 404. ### To record the replacement {#to-record-the-replacement} The Device Management application records every replacement in an event and an audit record. Create both with the same text. The text lists the external IDs before and after the replacement, each as ` []`, separated by commas. 1. Send a [Create an event](https://cumulocity.com/api/core/#operation/postEventCollectionResource) request: ```http POST /event/events Content-Type: application/json Accept: application/json { "source": { "id": "" }, "type": "c8y_DeviceReplaced", "time": "", "text": "Device with external ID(s) SN-0001 [c8y_Serial] was replaced by device with external ID(s) SN-0002 [c8y_Serial]" } ``` The platform returns HTTP 201 and the event with its `id`. The event appears in the **Events** tab of the device, see [Events](https://cumulocity.com/docs/device-management-application/viewing-device-details/#events). 2. Send a [Create an audit record](https://cumulocity.com/api/core/#operation/postAuditRecordCollectionResource) request: ```http POST /audit/auditRecords Content-Type: application/json Accept: application/json { "activity": "Device replaced", "source": { "id": "" }, "text": "Device with external ID(s) SN-0001 [c8y_Serial] was replaced by device with external ID(s) SN-0002 [c8y_Serial]", "time": "", "type": "Inventory", "user": "" } ``` The platform returns HTTP 201 and the audit record with its `id`. The record appears in the audit logs, see [Audit logs](https://cumulocity.com/docs/standard-tenant/monitoring/#audit-logs). The original device now has the external IDs of the replacement device, and the replacement device no longer exists. ## API reference ### Core API Reference: https://cumulocity.com/api/core/ - [GET /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/getManagedObjectResource): Retrieve a specific managed object - [GET /identity/globalIds/{id}/externalIds](https://cumulocity.com/api/core/#operation/getExternalIDCollectionResource): Retrieve all external IDs of a specific managed object - [GET /user/currentUser](https://cumulocity.com/api/core/#operation/getCurrentUserResource): Retrieve the current user - [GET /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/getExternalIDResource): Retrieve a specific external ID - [DELETE /identity/externalIds/{type}/{externalId}](https://cumulocity.com/api/core/#operation/deleteExternalIDResource): Remove a specific external ID - [POST /identity/globalIds/{id}/externalIds](https://cumulocity.com/api/core/#operation/postExternalIDCollectionResource): Create an external ID - [PUT /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/putManagedObjectResource): Update a specific managed object - [DELETE /inventory/managedObjects/{id}](https://cumulocity.com/api/core/#operation/deleteManagedObjectResource): Remove a specific managed object - [POST /event/events](https://cumulocity.com/api/core/#operation/postEventCollectionResource): Create an event - [POST /audit/auditRecords](https://cumulocity.com/api/core/#operation/postAuditRecordCollectionResource): Create an audit record ## Linked from the documentation - [Viewing all devices > To replace a device](https://cumulocity.com/docs/device-management-application/viewing-all-devices/#to-replace-a-device)