Posted Feb 26 by Peng Qiu.
Updated Feb 27.

This tutorial walks you through how to upload and download contents with ACS servers, BOCS servers or local REST servers in Documentum REST Services.

Last activity Feb 27 by Peng Qiu.
101 views. 0 comments.

Overview

A distributed content solution is utilized to handle upload and download for document contents in Documentum Server. It enables clients to upload the primary content of a sysobject to a cache sever in a separate call. Since cache servers can be deployed in the customer's local environment, the upload and download in wide area networks will be greatly accelerated.

Two main services to implement this solution are ACS (Accelerated Content Services) and BOCS (Branch Office Caching Services).

Prerequisite

Before you try out the samples in this tutorial, you need to set up the required servers and make sure that they are working.

Documentum Server (Content Server) and REST Services

Either your Content Server or REST Services should be running with version higher than 16.4 in order to use the Distributed Content features.

ACS Server

An ACS server is installed together with Documentum Server and deployed in the Documentum Java Method Server (DCTM JMS). Be sure that the DCTM JMS is running. Test the ACS server with the below URL with your web browser. The default port is 9080.

http://:/ACS/servlet/ACS

A one-line response will be returned if your ACS server works fine. Try restarting the DCTM JMS Service if it doesn't work.

ACS Server Is Running - Version : 16.4.0010.0010

The configuration object for the ACS server has already been created by the installation.

enter image description here

Make sure that the Base URL is accessible to the host that your BOCS server resides in.

enter image description here

BOCS Server

A BOCS Server is a separate, optional product with its own installer. A new service named Documentum Branch Office Caching Services should be running behind the scene if your installation succeeded. Test the BOCS server with the URL as below and the default port is 8086.

http://:/bocs/servlet/ACS

A response like this would be returned if you get everything right.

ACS Server Is Running - Version : 16.4.0000.0065

The further step is creating network locations and BOCS server configuration objects through Documentum Administrator (DA). All network locations and BOCS servers objects must be created and configured in your global registry repository.

Here a network location with ID shanghai and a BOCS server configuration object named BOCS-Shanghai have been created.

enter image description here

enter image description here

Notice to select the intended network location for your BOCS server. Besides, remember to add a base URL for the BOCS server as shown below.

enter image description here

Upload content to the ACS/BOCS Server

Before uploading content, we need to get the content upload URL. There are 3 resource methods that can generate the ACS/BOCS server content upload URL. They are POST on Folder Child Documents, Post on Folder Child Objects and Put on Lock. We will take POST on Folder Child Documents as an example.

Here is the workflow to complete the content upload.

enter image description here

There are some constraints to be noted for the ACS and BOCS content upload URLs.

  • Though there could be multiple ACS servers or BOCS servers deployed for a Content Server, only one ACS or BOCS content upload URL can be requested at a time.
  • Only a contentless (newly or existed) sysobject can be requested for ACS and BOCS content upload.
  • Only the primary content at page 0 can be requested for ACS and BOCS content upload.

Create a new document

Make a POST request to Folder Child Documents resource, in which the ACS/BOCS content upload URL is required through query parameters.

POST /dctm-rest/repositories/REPO/folders/0b00000180002973/documents?require-dc-write=true& format=crtext& content-length=10& network-location=shanghai HTTP/1.1
Host: 10.245.xxx.xxx:8080
Authorization: Basic QWRtaW5pc3RyYXRvcjpQYXNzd29yZEAxMjM=
Content-Type: application/vnd.emc.documentum+json

{
  "properties": {
      "object_name": "BOCS-Upload-doc.txt"
  }
}

Here is a brief explanation for the parameters.

  • require-dc-write: Specifies whether to request distributed content upload URL.
  • format: Content format for the content to upload. Required when require-dc-write is true.
  • content-length: Content length for the content in bytes. Required when require-dc-write is true.
  • network-location: Decides which BOCS server to upload if this network location exists and has a mapped BOCS server configuration. Otherwise, the ACS server URL is returned. Optional.

The response contains the link relation http://identifiers.emc.com/linkrel/distributed-upload and the upload URL. Notice that the r_content_size is 0 and a_content_type is empty for the new document.

{
    "name": "document",
    "type": "dm_document",
    ...
    "properties": {
        "object_name": "BOCS-Upload-doc.txt",
        "r_object_type": "dm_document",
        ...
        "a_content_type": "",
        "r_content_size": 0,
        ...
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/distributed-upload",
            "title": "BOCS-shanghai",
            "href": "http://<BOCS-SERVER>:8086/bocs/servlet/ACS?command=write&..."
        },
        ...
    ]
}

Upload the content

Make another POST request on the content upload URL to complete the upload.

POST /bocs/servlet/ACS?command=write&… HTTP/1.1
Host: 10.245.xxx.xxx:8086
Content-Type: text/plain
Authorization: Basic QWRtaW5pc3RyYXRvcjpQYXNzd29yZEAxMjM=

1234567898

When the content upload is completed, REST Client gets a 302 Moved Temporarily response from the ACS or BOCS server, where there is a Location header telling the document resource URL. The document is also unlocked upon the success of the content upload.

HTTP/1.1 302
Location: http://10.245.xxx.xxx:8080/dctm-rest/repositories/REPO/documents/090000018000xxxx

By this step, the distributed content uploading has been completed. REST Client can make the URL redirect request to the document resource again.The meta data of the document is returned with updated content type and content size.

{
    "name": "document",
    "type": "dm_document",
    "properties": {
        "object_name": "BOCS-Upload-doc.txt",
        "r_object_type": "dm_document",

        "a_content_type": "crtext",
        "r_content_size": 10,
        ...
    },
    ...
}

Download distributed content

In this section, we will download the distributed content from the ACS/BOCS server by using URI query parameters media-url-policy and network-location.

Get the primary content

From another tutorial Manage Document Contents in REST Services, we have learned that the primary content of a document can be retrieved through link relation http://identifiers.emc.com/linkrel/primary-content under the document resource.

GET /dctm-rest/repositories/REPO/objects/0900000180003106/contents/content HTTP/1.1
Host: 10.245.xxx.xxx:9080
Authorization: Basic QWRtaW5pc3RyYXRvcjpQYXNzd29yZEAxMjM=

You'll find the enclosure and http://identifiers.emc.com/linkrel/content-media link relations from the response. They are duplicated URLs pointing to the same target content media location. The link relation enclosure is duplicated to support Atom client.

Since the sample content we use here has already been uploaded to ACS server, the default links for the primary content will be pointed to the ACS server.

{
    "name": "content",
    "properties": {
        "object_name": "BOCS-Upload-doc.txt",
        ...
    },
    "links": [
        ...
        {
            "rel": "enclosure",
            "title": "ACS",
            "href": "http://10.245.42.41:9080/ACS/servlet/ACS?command=read&..."
        },
        {
            "rel": "http://identifiers.emc.com/linkrel/content-media",
            "title": "ACS",
            "href": "http://10.245.42.41:9080/ACS/servlet/ACS?command=read&..."
        },
        ...
    ]
}

Use parameter media-url-policy

With the URI parameter media-url-policy, you can get content media from all kinds of locations.

GET /dctm-rest/repositories/REPO/objects/0900000180003106/contents/content?media-url-policy=all HTTP/1.1
Host: 10.245.xxx.xxx:9080
Authorization: Basic QWRtaW5pc3RyYXRvcjpQYXNzd29yZ

All available links are returned as follows.

{
    "name": "content",
    "properties": {
        "object_name": "BOCS-Upload-doc.txt",
        ...
    },
    "links": [
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/content-media",
            "title": "ACS",
            "href": "http://10.245.42.41:9080/ACS/servlet/ACS?command=read&..."
        },
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/content-media",
            "title": "BOCS-shanghai",
            "href": "http://10.245.xxx.xxx:8086/bocs/servlet/ACS?command=read&..."
        },
        ...
        {
            "rel": "http://identifiers.emc.com/linkrel/content-media",
            "title": "LOCAL",
            "href": "http://10.245.xxx.xxx:9080/dctm-rest/repositories/REPO/objects/0900000180003106/content-media?format=crtext&modifier=&page=0"
        },
        ...
    ]
}

When media-url-policy is set to DC-PREF (its default value), the REST server tries to retrieve a distributed content URL first. If no distributed content URL is available, a Content Media resource URL from the REST server is still acceptable.

The parameter has two more valid values, LOCAL and DC-ONLY. For detailed explanation about them, please refer to Documentum Platform REST Services Reference Guide.

Use parameter network-location

By specifying a network location, you can get content media URLs from a BOCS server.

GET /dctm-rest/repositories/REPO/objects/0900000180003106/contents/content?network-location=shanghai HTTP/1.1
Host: 10.245.xxx.xxx:9080
Authorization: Basic QWRtaW5pc3RyYXRvcjpQYXNzd29yZ

Content media links for all available BOCS servers mapped to location shanghai will be returned.

{
    "name": "content",
    "properties": {
        "object_name": "BOCS-Upload-doc.txt",
        ...
    },
    "links": [
        {
            "rel": "enclosure",
            "title": "BOCS-shanghai",
            "href": "http://10.245.xxx.xxx:8086/bocs/servlet/ACS?command=read&..."
        },
        {
            "rel": "http://identifiers.emc.com/linkrel/content-media",
            "title": "BOCS-shanghai",
            "href": "http://10.245.xxx.xxx:8086/bocs/servlet/ACS?command=read&..."
        },
        ...
    ]
}

Conclusion

Through this tutorial, you have gained basic concepts and samples related to distributed contents, including:

  • How to configure ACS and BOCS servers for storing distributed content
  • The workflow and operations for uploading distributed content
  • How to download content media using parameters media-url-policy and network-location

Table of Contents

Your comment

To leave a comment, please sign in.