Tutorial: Manage Document Contents in REST Services

This doc shows a series of JSON message samples to create, update, and delete primary contents and renditions in Documentum REST Services(seeing IIG RESTful Web Services).

 

1. Assumed that you get a folder resource.

GET http://rest-demo/dctm-rest/repositories/acme01/folders/0b0004d2800051b6

Accept: application/vnd.emc.documentum+json

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

From the response, you'll find link relations "http://identifiers.emc.com/linkrel/documents" and "http://identifiers.emc.com/linkrel/objects" which point to the folder child documents and folder child sysobjects feeds, respectively.

folder.png

These two feeds allow you to create new documents/sysobjects under the folder.

 

2. Create a contentful document

You can post a multi-part HTTP request to the feed to create a contentful document directly with both properties and a primary content. Seeing the sample:

POST http://rest-demo/dctm-rest/repositories/acme01/folders/0b0004d2800051b6/documents

Accept: application/vnd.emc.documentum+json

Content-Type: multipart/form-data; boundary=vFKDeJ2jOu0ZQqKu9BGfHj9otiMJq44EwXfiV

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

 

--vFKDeJ2jOu0ZQqKu9BGfHj9otiMJq44EwXfiV

 

 

Content-Disposition: form-data; name="object"

Content-Type: application/vnd.emc.documentum+json;charset=UTF-8

 

{"properties":{"r_object_type": "dm_document", "object_name": "readme.txt"}}

--vFKDeJ2jOu0ZQqKu9BGfHj9otiMJq44EwXfiV

 

 

Content-Disposition: form-data; name="content"

Content-Type: plain/text; charset=UTF-8

 

Hello, ReSTer!

--vFKDeJ2jOu0ZQqKu9BGfHj9otiMJq44EwXfiV--

From the response, a new document resource is returned.

HTTP 201 Created

Location: http://rest-demo/dctm-rest/repositories/acme01/objects/090004d28000ba84

Content-Type: application/vnd.emc.documentum+json;charset=UTF-8

Content-Length: 4042

 

doc4.png

From the document resource, you'll find two link relations "contents" and "http://identifiers.emc.com/linkrel/primary-content" which point to the contents feed and the primary content of this document, respectively.

 

3. Create a contentless document

If your client app does not support HTTP multipart POST, you can create a contentful document in 2 steps. Firstly, create a contentless document under the folder.

POST http://rest-demo/dctm-rest/repositories/acme01/folders/0b0004d2800051b6/documents

Accept: application/vnd.emc.documentum+json

Content-Type: application/vnd.emc.documentum+json

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

 

{"properties":{"r_object_type": "dm_document", "object_name": "readme.txt"}}

Then, you could create a new primary content under the document contents feed.

 

4. Create a primary content

Following the "contents" link relation on the document resource, you can create a new primary content under the contents feed.

POST http://rest-demo/dctm-rest/repositories/acme01/objects/090004d28000ba84/contents

Accept: application/vnd.emc.documentum+json

Content-Type: text/plain

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

 

Hello, ReSTer!

The response returns you a content metadata resource for the newly created content.

content.png

The content metadata resource contains both metadata and media links of the content.

 

Please note that the format of the content is set as "atd" according to its mime type "text/plain". This is due to the fact of one-many mapping between mime type and formats in Content Server format type. The REST server picks up the default format for the mime type (in name ascending sequence) if the format is not set by the client explicitly. You could customize it in two ways:

  • append a URI query parameter "format=<YOUR_PREFERRED_FORMAT_NAME>" at the contents feed URI for POST.
  • Update REST server runtime properties to specify the default mime-to-format mapping in dctm-rest.war/WEB-INF/classes/rest-api-runtime.properties file.

rest.mime.format.mapping.enabled=true

 

 

# [repositoryName].[mime_type]=[format], support wildcard repository name

*.text/plain=text

my_repository.application/msword=msw12

 

5. Create a rendition

Besides the primary content, you can also create renditions under the same contents feed.

POST http://rest-demo/dctm-rest/repositories/acme01/objects/090004d28000ba84/contents?format=crtext&page=0&primary=false

Accept: application/vnd.emc.documentum+json

Content-Type: text/plain

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

 

Hello, ReSTer, for rendition!

For the rendition creation, you need to explicitly specify the format name, page number or page modifier. And it is mandatory to set "primary=false" if the content to create is actually a rendition.

 

The REST server returns you a rendition.

rendition.png

 

6. Update a content/rendition

To update an existing content or rendition, POST on the contents feed with the binary of the new content/rendition. In the URI of the contents feed, you need to specify on which format, page number and page modifier to update, and it is required to set the parameter "overwrite=true". For instance,

POST http://rest-demo/dctm-rest/repositories/acme01/objects/090004d28000ba84/contents?format=crtext&modifier=&page=0&overwrite=true

Accept: application/vnd.emc.documentum+json

Content-Type: text/plain

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

 

Hello, ReSTer, for rendition update!

 

7. Delete a content/rendition

To delete an existing content or rendition, DELETE on the "self" link relation of the content resource.

DELETE http://rest-demo/dctm-rest/repositories/acme01/objects/090004d28000ba84/contents?format=crtext&modifier=&page=0

Authorization: Basic ZG1hZG1pbjpwYXNzd29yZA==

 

8. Demo of large contentful document import

In below screenshot, I demonstrated the large content (a 4GB file) import using Chrome web browser + Documentum REST Services. In this demo, I used the Chrome extension DHC to submit the request. It also works on some other REST clients, like POSTMan.

 

Usecase: Import a 4GB file to a cabinet of the remote repository using HTTP multipart (a document = properties + content).

Snip20150204_19.png

 

In the DHC client, I added two parts to form the request, where the first is the properties of the new document, and the latter is the content file. Since I am not able to specify the media type for each part, I worked around it a bit.  Documentum REST Services takes JSON as the default media type, so I used JSON representation for the properties; besides, I specified the content format in the URI query, to overcome the limitation that I am not able specify the media type for the 2nd part. The request takes around 8 minutes to complete the 4GB file upload. As the result, the response returns the new document representation.

 

Learn more about Documentum REST Services >>