POST /api/dms/objects/{objectId}/versions/{versionNr}/actions/restore

Owned by Technische Redaktion
Last updated: Feb 16, 2023
As of Versionproduct version 2022 Spring | component version 2022 Spring
Request MethodPOST
Required Permissionaction write and read on the current version of the object
>> Roles and Role Sets
Description

Restores the old version of an object specified by objectId and versionNr.

The following requirements have to be matched by the object version specified by versionNr:

  • It has to exist and must not be the current version.
  • It has to be valid according to the current schema. E.g., if one of its properties is not part of the current schema anymore, the restoring process will fail.
  • If the current object version has been assigned a system:rmExpirationDate, the specified old object version must have the same system:rmExpirationDate.
  • If the current object version has a binary content file AND a system:rmExpirationDate that is not yet expired, the specified old object version must have the same binary content file AND the same system:rmExpirationDate.

Internally, the data of the old object version are used to update the current object version. Thus, a new object version is created that has the data of the specified old object version except for system:versionNumber, system:lastModifiedBy, system:lastModificationDate and system:traceId. Those properties describe the restoring action itself.

If tags are assigned to the current object before the restoring action, only those tags with a name ending with the suffix :resistant are transferred to the new object version.

A new entry in the object's audit trail is created. For the detail property, the value OBJECT_RESTORED_FROM_VERSION is set.

As of 2022 Summer: Optionally, the boolean query parameter restoreParentId can be appended to the request URL. This parameter is relevant for objects with a system:parentId property that indicates the object is considered as a child object of a folder object. The old version of the child object to be restored might have a different value for the system:parentId property. Thus, you might want to keep the current value for the system:parentId property of the child object even after restoring an old version.

  • If restoreParentId=true (default), the system:parentId value of the respective old object version is used.
  • If restoreParentId=false, the system:parentId value of the current version is used after restoring the respective old object version.

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

Request Example
/api/dms/objects/950f1e3a-829b-473d-97c5-9ea0a94706f6/versions/2/actions/restore
Result Example
{
    "objects": [{
        "properties": {
            "system:objectId": {
                "value": "950f1e3a-829b-473d-97c5-9ea0a94706f6"
            },
            "system:baseTypeId": {
                "value": "system:document"
            },
            "system:objectTypeId": {
                "value": "appEmail:email"
            },
            "system:createdBy": {
                "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
            },
            "system:creationDate": {
                "value": "2018-01-26T15:21:170Z"
            },
            "system:lastModifiedBy": {
                "value": "0d7fd0be-6a0b-4d3b-933c-25e0c4c5d794"
            },
            "system:lastModificationDate": {
                "value": "2018-01-26T15:21:170Z"
            },
            "system:versionNumber": {
                "value": 4
            },
            "system:tenant": {
                "value": "tenant1"
            },
            "system:traceId": {
                "value": "97a35859dbb4c435"
            },
            "appEmail:from": {
                "value": "Garco Meissler <garco@example.de>"
            },
            "appEmail:to": {
                "value": ["Dudreas Annkel <dudreas@example.de>"]
            },
            "appEmail:cc": {
                "value": ["Kruedeas Anger <kruedeas@example.de>",
                "Vils Normum <Normum@example.de>"]
            },
            "appEmail:subject": {
                "value": "Updated Bewerbungsunterlagen"
            },
            "table": {
                "columnNames": ["iColumn1", "iColumn2", "iColumn3"],
                "value": [["something", "to know", true],["more", "infos", false]]
            }
        },
        "contentStreams": [{
            "contentStreamId": "2B797243-A1F5-11EA-A814-9FABD98CE7A7",
            "length": 173413,
            "mimeType": "message/rfc822",
            "fileName": "upload.eml",
            "digest": "E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855",
            "repositoryId": "repo252"
        }]
    }]
}