v1 REST API - Part 5 - Versioning & Locking

cancel
Showing results for 
Search instead for 
Did you mean: 

v1 REST API - Part 5 - Versioning & Locking

gavincornwell
Senior Member
7 9 20K

In the last post we looked at how to retrieve, update and delete nodes, this time we're going to concentrate on versioning.

As always there is a Postman collection to accompany this post. To import the collection click on the "Run in Postman" button below.

Let's start by creating an empty file like we did in the last post by POSTing the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/-my-/children (1st request in the Postman collection):

{
  "name": "version.txt",
  "nodeType": "cm:content"
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

If you examine the response below you'll notice there's no mention of versioning at all, that's because empty files are created without versioning enabled.

Note: If you want to create content with versioning enabled by default use multipart/form-data instead of JSON, refer back to part 3 or see http://localhost:8080/api-explorer/#!/nodes/addNode for details.

{
  "entry": {
    "aspectNames": [
      "cm:auditable"
    ],
    "createdAt": "2016-11-10T21:35:04.389+0000",
    "isFolder": false,
    "isFile": true,
    "createdByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "modifiedAt": "2016-11-10T21:35:04.389+0000",
    "modifiedByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "name": "version.txt",
    "id": "fa100bae-9903-44e4-9e19-5a8523be7422",
    "nodeType": "cm:content",
    "content": {
      "mimeType": "text\/plain",
      "mimeTypeName": "Plain Text",
      "sizeInBytes": 0,
      "encoding": "UTF-8"
    },
    "parentId": "bd8f1283-3e84-4585-aafc-12da26db760f"
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

Now let's update the content like we did in the last post but this time also provide the majorVersion and comment query parameters.

To do this, PUT the body below with a Content-Type of text/plain to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... version (2nd request in Postman collection):

Note: You'll obviously need to replace fa100bae-9903-44e4-9e19-5a8523be7422 with the id from your response throughout this post.

This is the initial content for the file.‍‍‍‍‍‍‍‍

This should return a response similar to the one below:

{
  "entry": {
    "isFile": true,
    "createdByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "modifiedAt": "2016-11-10T21:48:28.014+0000",
    "nodeType": "cm:content",
    "content": {
      "mimeType": "text\/plain",
      "mimeTypeName": "Plain Text",
      "sizeInBytes": 41,
      "encoding": "ISO-8859-1"
    },
    "parentId": "bd8f1283-3e84-4585-aafc-12da26db760f",
    "aspectNames": [
      "cm:versionable",
      "cm:titled",
      "cm:auditable",
      "cm:author"
    ],
    "createdAt": "2016-11-10T21:35:04.389+0000",
    "isFolder": false,
    "modifiedByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "name": "version.txt",
    "id": "fa100bae-9903-44e4-9e19-5a8523be7422",
    "properties": {
      "cm:versionLabel": "1.0",
      "cm:versionType": "MAJOR"
    }
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

You can see from the response that the cm:versionable aspect has been applied (line 18) and two version properties have been set (lines 32 and 33), cm:versionLabel and cm:versionType.

Now versioning is enabled we can retrieve the version history for the file by using the URL http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (3rd request in the Postman collection):

{
  "list": {
    "pagination": {
      "count": 1,
      "hasMoreItems": false,
      "totalItems": 1,
      "skipCount": 0,
      "maxItems": 100
    },
    "entries": [
      {
        "entry": {
          "isFolder": false,
          "isFile": true,
          "modifiedAt": "2016-11-10T21:48:28.014+0000",
          "modifiedByUser": {
            "id": "test",
            "displayName": "Test Test"
          },
          "name": "version.txt",
          "versionComment": "First version",
          "id": "1.0",
          "nodeType": "cm:content",
          "content": {
            "mimeType": "text\/plain",
            "mimeTypeName": "Plain Text",
            "sizeInBytes": 41,
            "encoding": "ISO-8859-1"
          }
        }
      }
    ]
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

We can see from the response above that there's only one version right now so let's create another one. This time though we'll create a minor version by using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... version (4th request in Postman collection) and setting the content to:

This is the second version of the content, v1.1.‍‍‍‍‍‍‍‍

Now retrieve the version history again and you should see a response like the one shown below. This is also where you'll see the comments we specified (lines 21 and 42) when creating new versions.

{
  "list": {
    "pagination": {
      "count": 2,
      "hasMoreItems": false,
      "totalItems": 2,
      "skipCount": 0,
      "maxItems": 100
    },
    "entries": [
      {
        "entry": {
          "isFolder": false,
          "isFile": true,
          "modifiedAt": "2016-11-10T22:03:11.658+0000",
          "modifiedByUser": {
            "id": "test",
            "displayName": "Test Test"
          },
          "name": "version.txt",
          "versionComment": "Second version",
          "id": "1.1",
          "nodeType": "cm:content",
          "content": {
            "mimeType": "text\/plain",
            "mimeTypeName": "Plain Text",
            "sizeInBytes": 48,
            "encoding": "ISO-8859-1"
          }
        }
      },
      {
        "entry": {
          "isFolder": false,
          "isFile": true,
          "modifiedAt": "2016-11-10T21:48:28.014+0000",
          "modifiedByUser": {
            "id": "test",
            "displayName": "Test Test"
          },
          "name": "version.txt",
          "versionComment": "First version",
          "id": "1.0",
          "nodeType": "cm:content",
          "content": {
            "mimeType": "text\/plain",
            "mimeTypeName": "Plain Text",
            "sizeInBytes": 41,
            "encoding": "ISO-8859-1"
          }
        }
      }
    ]
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

As you'd expect, if we retrieve the content for the node using http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (5th request in Postman collection) we get:

This is the second version of the content, v1.1.‍‍‍‍‍‍‍‍


We can still get the content of the initial version though, to do this we have to use http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (6th request in the Postman collection), this gives us our original content:

This is the initial content for the file.‍‍‍‍‍‍‍‍


Imagine we change our mind and decide we want to revert to a previous version. To revert to version 1.0 we have to POST the following body to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (7th request in the Postman collection):

{
  "majorVersion": true,
  "comment": "Reverted to original"
}‍‍‍‍‍‍‍‍‍‍‍‍


‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍We are able to specify whether the reverted version will create a new minor or major version and again provide a comment describing the reason for the additional version.

If you get the content now it should be back to what it was when we originally created the file and if you get the version history you'll see we now have an extra version, a 2.0.

Now, what if you wanted to make some changes to a file and not let anyone else make changes until you've finished?

For this situation we can lock the file by POSTing an empty JSON object (see below) to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (8th request in the Postman collection).

{}‍‍‍‍‍‍‍‍


‍This results in the response below, which shows the node has been locked (lines 31, 32 and 38).

{
  "entry": {
    "isFile": true,
    "createdByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "modifiedAt": "2016-11-10T22:07:41.857+0000",
    "nodeType": "cm:content",
    "content": {
      "mimeType": "text\/plain",
      "mimeTypeName": "Plain Text",
      "sizeInBytes": 41,
      "encoding": "ISO-8859-1"
    },
    "parentId": "bd8f1283-3e84-4585-aafc-12da26db760f",
    "aspectNames": [
      "cm:versionable",
      "cm:lockable",
      "cm:auditable"
    ],
    "createdAt": "2016-11-10T21:35:04.389+0000",
    "isFolder": false,
    "modifiedByUser": {
      "id": "test",
      "displayName": "Test Test"
    },
    "name": "version.txt",
    "id": "fa100bae-9903-44e4-9e19-5a8523be7422",
    "properties": {
      "cm:lockType": "WRITE_LOCK",
      "cm:lockOwner": {
        "id": "test",
        "displayName": "Test Test"
      },
      "cm:versionType": "MAJOR",
      "cm:versionLabel": "2.0",
      "cm:lockLifetime": "PERSISTENT"
    }
  }
}‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

There are a few options when using lock, see http://localhost:8080/api-explorer/#!/nodes/lockNode for more details. It's also possible to include an isLocked property when retrieving a node or a children listing so that your client does not need to parse these properties.

As the owner of the lock we can make changes to the file including the content, use the same update content URL we used earlier (2nd or 4th request in the Postman collection) to update the content and generate a new version.

However, if you try the same request as another user you'll get a 409 Conflict error response.

To unlock the file once you're done with your changes you can POST an empty JSON object (see below) to http://localhost:8080/alfresco/api/-default-/public/alfresco/versions/1/nodes/fa100bae-9903-44e4-9e1... (9th request in the Postman collection)

{}‍‍‍‍‍‍‍‍


‍We've almost covered all the functionality provided by the /nodes API, next time we'll look at the last remaining area, associations.

9 Comments
jego
Partner

Thanks for the updates.

It is possible to unlock any document as admin via rest api?

gavincornwell
Senior Member

Yes, it is possible to use admin to unlock any document.

vicevaldes
Member II

I believe that I have not obtained positive results following these steps, I have tried with php and I have added the arguments in the data sent in the following way:

 

<?php

 

//DATA

$ticket ='xxxxx';

$pdfnode = xxxx;

$server = 'xxxx';

$port = ':xxxx';

$filename = '../informeGeneradores/files/minuta12.pdf';

$type = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';

$url = $server.$port.'/alfresco/api/-default-/public/alfresco/versions/1/nodes/'.$pdfnode.'/children?alf_ticket='.$ticket;

 

$ch = curl_init($url);

 

$args = new CurlFile($filename,$type,$filename);

 

$data = array(

'filedata'=>$args,

'nodeType'=>'cm:content',

'MajorVersion'=>'true',

'name'=> 'version',

'comment'=>'First'

);

 

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

curl_setopt($ch, CURLOPT_HEADER, false);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

curl_setopt($ch, CURLOPT_VERBOSE, true);

 

$result = curl_exec($ch);

echo $result;

?>

 

So far no problems and I get the same results of this article. but nevertheless when changing MajorVersion = true by false it throws me the following error: 

{"error":{"errorKey":"version already exists.","statusCode":409,"briefSummary":"04250716 version already exists.","stackTrace":"Por motivos de seguridad, ya no se muestra el seguimiento de la pila, pero se guarda la propiedad para versiones anteriores.","descriptionURL":"https://api-explorer.alfresco.com"}}

 

I hope you can help me solve this problem.

yogeshpj
Established Member

Is it possible to get version noderef info when I am hitting nodes/{Node Id}/versions rest call ?

Any other way to get version noderef ( not the version label or id) using REST services ?

gavincornwell
Senior Member

No, the REST API does not expose the underlying NodeRef of any node.

mahi6a1985
Member II

Thanks for the brief explanation and it has helped me a lot.

Is the same mechanism available for files that are uploaded? Can we maintain versions for files that are uploaded like PDF etc. ?? Thanks in advance. Smiley Happy

gavincornwell
Senior Member

Yes, you can maintain versions for uploaded files.

mahi6a1985
Member II

Thank you for the prompt response. It will be very helpful if you share a link where I can find the relevant documentation and APIs to achieve this.

gavincornwell
Senior Member

I may have mis-understood your original question, but when you update the content of any node in the system (regardless of how it got there) you can provide parameters to control the versioning behaviour using this endpoint: Alfresco Content Services REST API Explorer (PUT /nodes/id/content).

Hope that helps!