DELETE /api/dms/objects

Owned by Team Oktopus
Last updated: May 25, 2023 by Technische Redaktion
12 min read
As of Versionproduct version 2021 Winter | breaking change with product version 2023 Spring (find the previous behavior below)
Request MethodDELETE
Response FormatJSON
Required Permission

action delete and read
>> Roles and Role Sets

Description

Deletes multiple objects specified by ID in the JSON request body.

The number of objects that can be deleted simultaneously via this endpoint is limited to 100.

If other properties beside system:objectId are specified in the request body, they are ignored. Especially, the result list of a search response can thus directly be sent as request body to delete all included objects.

The individual deletion sub-processes follow the procedure described for the DELETE /api/dms/objects/{objectId} endpoint.

As of 2023 Summer, the optional query parameter waitForSearchConsistency can be added to the request URL. If not specified, the default value true is used.

As of version 2023 Spring, the optional boolean query parameter greedy (default false) is available.

  • If greedy=false, the entire request fails as soon as one of the referenced objects cannot be found or cannot be deleted.
  • If greedy=true, deletion process is continued by deleting as many referenced objects as possible.

A proper response of the endpoint is structured as follows:

  • The HTTP status code is always 207.
  • The JSON response body contains the DMS objects (completed as far as possible) that were referenced by objectId in the request body.
  • Each DMS object has an options section containing the system:deletionResult with httpStatusCode, serviceErrorCode and message for the individual deletion process as displayed in the example response below.
  • Meaning of the individual values for httpStatusCode:
    • 200 OK - The object was deleted.
    • 403 Forbidden - Insufficient permissions for the object.
    • 404 Not Found - The object ID was not found.
    • 409 Conflict - The deletion is not allowed as it is against the rules (e.g., non-empty folder or document under retention).
    • 422 Unprocessable Entity - Other objects within the request could not be deleted and greedy=false.
Request HeaderContent-Type: application/json
Request Example

/api/dms/objects?greedy=false

The object IDs of the objects to be deleted are passed in the request body in JSON format.

{
	"objects": [{
		"properties": {
			"system:objectId": {
				"value": "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
			}
		}
	},
	{
		"properties": {
			"system:objectId": {
				"value": "903f2ae8-2cfc-476c-8386-55c6811e41da"
			}
		}
	},
	{
		"properties": {
			"system:objectId": {
				"value": "invalid"
			}
		}
	},
	{
		"properties": {
			"system:objectId": {
				"value": "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
			}
		}
	}]
}

Response Example

HTTP status code: 207

As greedy=false was set, the last object was not deleted because other objects within the request could not be deleted.

{
    "objects": [
        {
            "properties": {
                "system:objectId": {
                    "value": "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
                },
                "system:traceId": {
                    "value": "1234567887654321"
                },
                "system:objectTypeId": {
                    "value": "appFolder:akte4"
                },
                "system:lastModificationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "appFolder:title": {
                    "value": "folderwithcontent"
                },
                "system:baseTypeId": {
                    "value": "system:folder"
                },
                "system:tenant": {
                    "value": "tenant1"
                },
                "system:createdBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                },
                "system:creationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:lastModifiedBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                }
            },
            "options": {
                "system:deletionResult": {
                    "httpStatusCode": 409,
                    "serviceErrorCode": 2800,
                    "message": "A non-empty folder cannot be deleted."
                }
            }
        },
        {
            "properties": {
                "system:objectId": {
                    "value": "903f2ae8-2cfc-476c-8386-55c6811e41da"
                },
                "system:traceId": {
                    "value": "1234567887654321"
                },
                "system:objectTypeId": {
                    "value": "appFolder:akte4"
                },
                "system:lastModificationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "appFolder:title": {
                    "value": "undeletable"
                },
                "system:baseTypeId": {
                    "value": "system:folder"
                },
                "system:tenant": {
                    "value": "tenant1"
                },
                "system:createdBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                },
                "system:creationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:lastModifiedBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                }
            },
            "options": {
                "system:deletionResult": {
                    "httpStatusCode": 403,
                    "serviceErrorCode": 2810,
                    "message": "Insufficient permissions to perform an 'DELETE' action. IDs: 7b7616c0-c03d-47ee-9664-4b6d9e5ca8a1"
                }
            }
        },
        {
            "properties": {
                "system:objectId": {
                    "value": "invalidId"
                }
            },
            "options": {
                "system:deletionResult": {
                    "httpStatusCode": 404,
                    "serviceErrorCode": 2811,
                    "message": "Object not found. Objectid: invalidId"
                }
            }
        },
        {
            "properties": {
                "system:objectId": {
                    "value": "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
                },
                "system:traceId": {
                    "value": "1234567887654321"
                },
                "system:objectTypeId": {
                    "value": "appFolder:akte4"
                },
                "system:lastModificationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:versionNumber": {
                    "value": 1
                },
                "appFolder:title": {
                    "value": "deletablefolder"
                },
                "system:baseTypeId": {
                    "value": "system:folder"
                },
                "system:tenant": {
                    "value": "tenant1"
                },
                "system:createdBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                },
                "system:creationDate": {
                    "value": "2023-02-14T14:53:11.690Z"
                },
                "system:lastModifiedBy": {
                    "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
                }
            },
            "options": {
                "system:deletionResult": {
                    "httpStatusCode": 422,
                    "serviceErrorCode": 0,
                    "message": "Not deleted. Process stopped due to conflicts with other objects in the batch."
                }
            }
        }
    ]
}


Behavior up to 2022 Winter:

As of Versionproduct version 2021 Winter | component version 2021 Winter
Request MethodDELETE
Response FormatHTTP status code
Required Permission

action delete and read
>> Roles and Role Sets

Description

Deletes multiple objects specified by ID in the JSON request body.

A delete permission is required for all objects. A folder cannot be deleted if it is not empty (see DELETE /api/dms/objects/{objectId}).
If the object for at least one ID cannot be found or cannot be deleted, the whole request fails.

The number of objects that can be deleted simultaneously via this endpoint is limited to 100.

All old versions of the referred objects are deleted as well.

The assigned binary content files are only deleted from the repository if no other object or object version refers to them.

In the audit trail, the entries 202 and 200 are created for each deleted object. All previous audit entries for the deleted objects remain in the database and can still be retrieved via search.

If other properties beside system:objectId are specified in the request body, they are ignored. Especially, the result list of a search response can thus directly be sent as request body to delete all included objects.

Request HeaderContent-Type: application/json
Request Example

The object IDs of the objects to be deleted are passed in the request body in JSON format.

{
	"objects": [{
		"properties": {
			"system:objectId": {
				"value": "cdc7095f-a5ce-486d-92a7-6d0955d969ee"
			}
		}
	},
	{
		"properties": {
			"system:objectId": {
				"value": "cdc7106f-a5ce-597d-92a7-1d1166d171ee"
			}
		}
	}]
}

Result Example

no result

Response
Meaning of the response status codes:

200 OK

All DMS objects were deleted.

403 Forbidden

Insufficient permissions for at least one object.

404 Not Found

At least one of the specified objects cannot be found.

409 Conflict

At least one of the specified objects cannot be deleted due to retention (for more details click here).