0% found this document useful (0 votes)
970 views56 pages

D2FS REST Services Development Guide RESTBoardReview

Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
970 views56 pages

D2FS REST Services Development Guide RESTBoardReview

Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as DOC, PDF, TXT or read online on Scribd
You are on page 1/ 56

EMC® Documentum® D2FS REST

Services

Abstract
This document is a guide to using EMC Documentum
D2FS REST Services to utilize the D2 Configurations on
Documentum Repositories.

February 2020
Copyright © 2020 EMC Corporation. All Rights Reserved.

EMC believes the information in this publication is


accurate as of its publication date. The information is
subject to change without notice.

The information in this publication is provided “as is.”


EMC Corporation makes no representations or
warranties of any kind with respect to the information in
this publication, and specifically disclaims implied
warranties of merchantability or fitness for a particular
purpose.

Use, copying, and distribution of any EMC software


described in this publication requires an applicable
software license.

For the most up-to-date listing of EMC product names,


see EMC Corporation Trademarks on EMC.com.

2
Table of Contents
Overview 8
What are D2FS REST Services? 8
Consuming D2FS REST Services 8
Relationship with other Documentum Platform APIs 10
General REST Definitions 10
Common Definition - HTTP Headers 10
Common Definition – Query Parameters 11
HTTP Status Codes 11
Supported MIME Types 11
HTTP Methods 11
Link Relations 12
Public Link Relation Registry 12
D2FS Link Relations 13
Explore the D2FS REST services 16
Common Tasks 16
Resources 16
Organization of Resource Reference Documentation 16
Profiles 16
URI Template 16
Feed 17
Link Relation 17
Operations 17
Get Profiles-D2 17
HTTP Method 17
Server Accepted Request Media Types 17
Query Parameters 18
Request Headers 18
Request Body 18
Response Headers 18
Supported Response Media Types 18
Response Status 18
Profile 19
URI Template 19
Link Relation 19
Operations 19
Get a Profile 19
HTTP Method 19

3
Server Accepted Request Media Types 19
Query Parameters 20
Request Headers 20
Request Body 20
Response Headers 20
Supported Response Media Types 20
Response Status 20
Search Configurations 20
URI Template 20
Feed 22
Link Relation 22
Operations 22
Get Profiles-D2 22
HTTP Method 22
Server Accepted Request Media Types 22
Query Parameters 23
Request Headers 23
Request Body 23
Response Headers 23
Supported Response Media Types 23
Response Status 23
Search Configuration 23
URI Template 24
Link Relation 24
Operations 24
Get a Profile 24
HTTP Method 24
Server Accepted Request Media Types 24
Query Parameters 24
Request Headers 24
Request Body 25
Response Headers 25
Supported Response Media Types 25
Response Status 25
Types 25
URI Template 25
Feed 25
Link Relation 26
Operations 26
Get Types-D2 26

4
HTTP Method 26
Server Accepted Request Media Types 26
Query Parameters 26
Request Headers 26
Request Body 27
Response Headers 27
Supported Response Media Types 27
Response Status 27
Type 27
URI Template 27
Link Relation 28
Operations 28
Get a Type 28
HTTP Method 28
Server Accepted Request Media Types 28
Query Parameters 28
Request Headers 28
Request Body 28
Response Headers 29
Supported Response Media Types 29
Response Status 29
Templates 29
URI Template 29
Link Relation 29
Operations 29
Get Templates 30
HTTP Method 30
Server Accepted Request Media Types 30
Query Parameters 30
Request Headers 30
Request Body 30
Response Headers 30
Supported Response Media Types 30
Response Status 30
Create Object Content using Templates 31
URI Template 31
This URI template will be replaced with /repositories/
{repositoryName}/objects/{objectId}. 31
Operations 31
HTTP Method 31

5
Server Accepted Request Media Types 31
Query Parameters 31
Request Headers 31
Request Body 31
Response Headers 32
Supported Response Media Types 32
Response Status 32
Preview URLS32
URI Template 32
Link Relation 32
Operations 32
Get Preview Urls 33
HTTP Method 33
Server Accepted Request Media Types 33
Query Parameters 33
Request Headers 33
Request Body 33
Response Headers 33
Supported Response Media Types 33
Response Status 33
Examples 35
Object Creation 36
URI Template 36
Link Relation 36
Operations 37
HTTP Method 37
Server Accepted Request Media Types 37
Query Parameters 37
Request Headers 37
Request Body 37
Examples 37
Object Versioning 38
URI Template 38
Link Relation 39
Other Details 39
C2 View & Print 46

Sample Steps 39
Viewing profiles, types 39

6
Content creation 45
Create Object without content 45
Create Object with content 47
References 48

7
Overview
This document is a guide to using EMC D2FS REST services.
Documentum-D2 provides two clients – D2-Config and D2 Client. D2
Config is the administration client of Documentum D2. D2 Client is a web-
based application for users that provides the ability to interact with
content in one or more repositories.
D2FS REST services help any REST client to utilize configurations that are
defined as part of D2-Config. This documentation is intended for
developers and architects who are building clients against the D2FS REST
Services.

What are D2FS REST Services?


EMC D2FS REST Services are a set of RESTful web service interfaces that
interact with the D2 Configurations and honor them as required. Being
developed in a purely RESTful style, D2FS REST Services provides you
with high efficiency and simplicity in programming, and also makes all
services easy to consume. These advantages make D2FS REST Services
the best choice for next generation applications and mobile applications
to interact with the D2 Configurations.
D2FS REST Services are written as part of the extensibility feature of the
EMC Documentum Platform REST services (also called as Documentum
REST services). Hence, the REST services provided by the Documentum
REST services and D2FS co-exist in the D2 server space. Currently, D2FS
REST services which have corresponding link relations and URLs in
Documentum REST are identified by the suffix : “-d2” in their link relations
and URL over the existing resources provided by Documentum REST
services. For any new service which is specific to D2FS, the link relation
may not carry the suffix.
Similar to the Documentum REST services, D2FS REST Services models
objects in Documentum repositories as resources and identifies resources
by Uniform Resource Identifiers (URIs). It defines specific media types to
represent resources and drives application state transfers by using link
relations. It uses a limited number of HTTP standard methods (GET, PUT,
POST, and DELETE) to manipulate resources over the HTTP protocol. D2FS
REST Services supports the JSON and XML format for resource
representation. D2FS REST Services does not introduce any new media
types and uses the existing ones that are available as part of the
Documentum REST services.

8
Consuming D2FS REST Services
D2 REST Services delivers a deployable Java web archive (WAR) that runs
in a web container of Java EE application server (refer to release notes for
system requirements). It exposes the interface as network-accessible
resources identified by URIs. D2 REST Services is programming language
independent. Therefore, you can consume the services by using any
language that has a HTTP client library, such as Java, .NET, Python, Ruby,
and so on. Because of these features, D2 REST Services doesn’t ship any
kind of client or SDK (Software Development Overview Kit) to the users.
You can take full freedom and ownership to develop the REST client to
consume the REST service if you follow hypertext-driven principles.

9
Relationship with other Documentum Platform APIs

D2 REST Services relies on the D2FS library to perform operations based on the
D2 Configurations available in the Documentum Content Server. D2FS library in
turn uses DFC and thus the communication between the REST server and Content
Server is conducted over Netwise RPC. D2 REST Services is a lightweight
alternative to the existing D2FS SOAP Services. However, it is not intended to
provide the equivalent functionalities in the initial release. You can leverage the
simplicity of RESTful services to achieve highly productive programming.

General REST Definitions


Common Definition - HTTP Headers

D2 REST Services supports the following common HTTP headers.

Http Header Description In Request Value Range


Name or Response
Authorization Authorization Request HTTP basic authentication
header header
for with the credential part
authentication encoded, for
example:
Authorization: Basic
QWxhZGRpbjpvcGVuIHNlc2Ft
ZQ==
Or, Kerberos authentication
header
with the credential part
encoded, for
example:
Authorization: Negotiate
YIIZG1hZG1pbjpwYXNzd29yZ
...
Accept Acceptable Request See the topic, "Supported
media type for MIME Types."
the response
Content-Type MIME type of Request See Supported MIME Types.
the /Response The REST server ignores the
request body or charset parameter in the
response body Content-Type header.
Location URI of the Response URI
newly-created

10
resource
Content-Length Size of the Request Non-negative number
entity-body, /Response
in decimal
number of
OCTETs, sent to
the
recipient

Common Definition – Query Parameters


D2 supports the following common query parameter:
- Inline
The rest of the query params remain unsupported as the extensibility
framework does not have options to consume an existing collection.
Please refer to the “Common Definition - Query Parameters” section of the
Documentum Platform REST services – Developer Guide for detailed
information on query parameters. Their purpose and meaning remains the
same as detailed in the Developer Guide.

HTTP Status Codes


Please refer to the “Http Status Codes” section of the Documentum
Platform REST services – Developer Guide for detailed information on list
of status codes that will be returned by the services. Their purpose and
meaning remains the same as detailed in the Developer Guide.

Supported MIME Types


A media type (also called a content type or MIME type) is a short string
identifying the format of a document. Once you know a document’s media
type, you can parse it. As described in the D2FS REST services section,
the services does not introduce any new MIME types, it uses the ones that
are already available with the Documentum Platform REST services.
Please refer to the “Supported MIME Types” section of the Documentum
Platform REST services – Developer Guide for detailed information on list
of supported MIME types. Their purpose and meaning remains the same
as detailed in the Developer Guide.

HTTP Methods
Documentum D2FS REST Services supports the following HTTP methods:
• GET

11
Use this method to retrieve a representation of a resource.
• POST
Use this method to create new resources, or update existing resources.
• DELETE
Use this method to delete a resource.

Link Relations
The D2FS REST service is a hypermedia driven API. Link relation forms the
basis of hypermedia driven APIs. The key purpose of a link relation type is
to act as an identifier for the semantics associated with the link. The client
chooses one of the available link relations for a state transition of either
an application or a resource.
D2FS introduces new link relations that can help to access the D2 specific
resources and to consume the existing D2 Configurations.
Clients are always required to use the link relations that are provided by
the server for state transition. The link relations are immutable and the
links(“href”) are constructed at runtime depending on the client’s
application state.
Link relations are not URIs, the URI that they refer to provide information
on how to use these link relations. Client need to refer to the actual links
“href” associated with the link relations to achieve state transition of
resources.

Public Link Relation Registry


The Internet Assigned Numbers Authority (IANA) maintains the public link
relations registry here: http://www.iana.org/assignments/link-relations.
The following describes those that are used within D2FS REST Services
with links to the detailed specifications.

Link Relation Description Specification


edit Points to a http://tools.ietf.org/html/rfc5023
resource that can
be used to edit
the link’s context.
self Conveys an http://www.ietf.org/rfc/rfc4287
identifier for the
link’s context.

12
13
D2FS Link Relations
These are link relations defined within EMC for use by D2FS REST
Services.

Link Relation Description Applicat


ion
State
http://identifiers.emc.com/lin Provides a href to the After the user
krel/ creation-profiles Creation Profiles resource. logins into a
This resource allows you repository space.
access the list of creation
profiles configured in D2-
Config.
http://identifiers.emc.com/lin Provides a href to the After the user
krel/ creation-profile Creation Profile resource. This gets into the list
resource allows you access to of creation
a specific profile configured in profiles.
D2-Config.

http://identifiers.emc.com/lin Provides a href to the list of After the user


krel/ type-configurations types defined within the gets into a
selected creation profile in D2 specific creation
Config. profile.
http://identifiers.emc.com/lin Provides a href to a specific After the user
krel/ type-configuration type within the selected gets into the list
creation profile in D2 Config. of types for a
specific profile
configuration.
http://identifiers.emc.com/lin Provides a href to create an After the user
krel/ object-creation object honoring the D2 logins into a
Configuration provided. repository space.

http://identifiers.emc.com/lin Provides a href to the After the user


krel/ document-templates Templates resource. This gets into a
resource allows you access specific
the list of template document/object.
documents configured in D2-
Config.
http://identifiers.emc.com/lin Provides a href to the After the user
krel/ document-template Template resource. This gets into a list of
resource allows you access template

14
the specific template documents.
configured in D2-Config.

http://identifiers.emc.com/lin Provides a href to the After the user


krel/comments Comments resource. This gets into a
resource allows you access specific
the list of comments on the document/object.
document.

http://identifiers.emc.com/lin Provides a href to the After the user


krel/comment Comment resource. This gets into a list of
resource allows you to access comments.
a specific comment.

The link relations appear in the relevant application state within the
context of the client.

The below link relations will exist until the Core REST extensibility is in
place. Once, extensibility is used in D2FS REST services, then the below
link relations will cease to exist.

Link Relation Description Applicat


ion
State
http://identifiers.emc.com/link Provides a href to create an After the user
rel/ object-creation object honoring the D2 logins into a
Configuration provided. repository space.
This will be overriding core
REST link relations in
Document Resource, Folder
Child Object Resource where
creation of object is
applicable. Refer below for
more details.
http://identifiers.emc.com/link Provides a href to After the user
rel/checkout/ checkout/lock this object. gets into a
This will be overriding core specific
REST link relation which is document/object.
applicable for checkout/lock.

15
http://identifiers.emc.com/link Provides a href to cancel After the user
rel/cancel-checkout checkout/unlock this object. gets into a
This will be overriding core specific
REST link relation which is document/object.
applicable for cancel
checkout/unlock.
http://identifiers.emc.com/link Provides a href to check-in After the user
rel/checkin-next-major next major version of this gets into a
object. This will be overriding specific
core REST link relation which document/object.
is applicable for check-in
next major version.
http://identifiers.emc.com/link Provides a href to checkin After the user
rel/checkin-next-minor next minor version of this gets into a
object. This will be overriding specific
core REST link relation which document/object.
is applicable for check-in
next minor version.
http://identifiers.emc.com/link Provides a href to checkin After the user
rel/checkin-branch branch version of this object. gets into a
This will be overriding core specific
REST link relation which is document/object.
applicable for check-in
branch version.

http://identifiers.emc.com/link Provides a href to checkin After the user


rel/checkin-same same version of this object. gets into a
This will be overriding core specific
REST link relation which is document/object.
applicable for check-in same
version.
http://identifiers.com/com/link Provides a href to the After the user
rel/preview-urls preview urls resource. This gets into a
resource allows you access specific
the list of preview urls on the document/object.
document. This will be
overriding core REST link
relation which is applicable
for Content/Contents
Resource.
The link relation: http://identifiers.emc.com/linkrel/object-creation which is used for
object creation will be overriding link relations such as:
http://identifiers.emc.com/linkrel/objects, http://identifiers.emc.com/linkrel/documents
and the like where object creation is applicable.

16
Explore the D2FS REST services
This section provides a sample which guides you through how to use the
D2FS REST services.
This sample uses JSON representation and collection pattern to represent
feeds. This assumes that the D2FS REST service is deployed in
localhost:8080 and the client is a web-browser capable of rendering JSON
results.

Common Tasks
The common tasks that are currently available in the D2FS REST services
is to
A) Understand the list of creation profiles that are available for a user
B) Understand the list of types that are available within a specific profile
C) Understand the configurations present on a specific type
D) Create an object of a specific type that honors the D2-Configurations
E) Understand the list of templates available for an object
E) View/add new/delete existing comments to an existing object in the
repository

Resources
Organization of Resource Reference Documentation
These guidelines apply to each resource reference documentation entry:
• All method parameters are optional unless otherwise noted.
• DELETE and GET methods do not have a request body.

Profiles
The profiles resource represents a collection of all the profiles that are
available in the context of the user.

URI Template
/repositories/ {repositoryName}/ profile-configuration
repositoryName Name of the repository

17
18
Feed

Feed Id Feed Title Updated Entry Supports


POST or
not
URI of the List of D2 Server’s current Profile NO
Creation Creation time
Profiles Profiles
resource
without
the file
extension

Entry Id Entry Title


URI of the Creation Profile Profile Name

Link Relation

Link Relation Description


self URI of the Creation Profile collection feed

Operations

Method Description
GET Lists all the creation profiles in the
repository for the current user’s context.

Get Profiles-D2
Lists all the creation profiles in the repository for the current user’s context.

HTTP Method
GET

Server Accepted Request Media Types


None

19
Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Length
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/atom+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
403 - Permission denied
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the D2 Creation Profiles collection.
• The body contains a list of D2 Creation Profiles.
• Each object may contain all properties of the creation profile, depending on the
setting of the query parameter (inline = true).
• The returned child objects collection only contains those that the user has
access to.
• Each profile entry must contain link that point to a specific profile.

20
Profile
The profile resource represents a creation profile in the repository.

URI Template
/repositories/ { repositoryName }/ profile-configuration /{profileId}
repositoryName Name of the repository
profileId Object ID of the Creation Profile

Link Relation

Link Relation Description


self Link to this creation profile
type-configuration [1] Collection of types that are defined as
part of this profile

1] This link relation is defined by Documentum. The fully qualified Documentum link
relation
path is prefixed with the following string:
http://identifiers.emc.com/linkrel/

Operations

Method Description
GET Retrieves properties, and other
information of the Creation profile
resource.

Get a Profile
Gets properties and other information of this Creation Profile. Properties are
returned as embedded elements in the response message body. Other information,
such as types, is referenced from the link relations of the response message body.

HTTP Method
GET

Server Accepted Request Media Types


None

21
Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
404 – D2 Creation Profile not found.
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the D2 Creation Profile.

Search Configurations
The search configurations resource represents a collection of all the
search configurations that are available in the context of the user.

URI Template
/repositories/ {repositoryName}/ search-configuration
repositoryName Name of the repository

22
23
Feed

Feed Id Feed Title Updated Entry Suppor


ts
POST
or not
URI of the List of D2 Server’s current Search NO
Search Search time Configurati
Configuratio Configuration on
ns resource s

Entry Id Entry Title


URI of the Search Configuration Search Configuration name

Link Relation

Link Relation Description


self URI of the Search Configuration collection
feed

Operations

Method Description
GET Lists all the search configurations in the
repository for the current user’s context.

Get Search Configurations


Lists all the search configurations in the repository for the current user’s context.

HTTP Method
GET

Server Accepted Request Media Types


None

24
Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Length
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/atom+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
403 - Permission denied
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the D2 Search Configurations collection.
• The body contains a list of D2 Search Configurations.
• Each object may contain all properties of the search configuration, depending on
the setting of the query parameter (inline = true).
• The returned child objects collection only contains those that the user has
access to.
• Each search configuration entry must contain link that point to a specific
configuration.

25
Search Configuration
The search configuration resource represents a search configuration in the
repository.

URI Template
/repositories/ { repositoryName }/ search-configuration /{configId}
repositoryName Name of the repository
configId Object ID of the Search Configuration

Link Relation

Link Relation Description


self Link to this search configuration

Operations

Method Description
GET Retrieves the types names, attribute
names, facets and other data associated
with a D2 Search Configuration.

Get a Search Config


Gets types, attributes and other information of this Search Configuration. The
data is returned as embedded elements in the response message body.

HTTP Method
GET

Server Accepted Request Media Types


None

Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type

26
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
404 – D2 Creation Profile not found.
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the D2 Creation Profile.

Types
The types resource represents a collection of all the types that are defined
in a specific D2 Creation profile.

URI Template
/repositories/ {repositoryName}/ type-configuration?profile={profileId}
repositoryName Name of the repository
profileId Object ID of the Creation Profile
(mandatory)

Feed

Feed Id Feed Title Updated Entry Supports


POST or
not

27
URI of the List of types Server’s current Type NO
types time
resource
without
the file
extension

Entry Id Entry Title


URI of the type Type Name

Link Relation

Link Relation Description


self URI of the D2 Types collection feed for
this profile.

Operations

Method Description
GET Lists all the D2 Types in the repository for
this creation profile.

Get Types-D2
Lists all the types configured for the specific creation profile.

HTTP Method
GET

Server Accepted Request Media Types


None

Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept

28
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Length
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/atom+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
403 - Permission denied
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the D2 Types collection.
• The body contains a list of types configured for this creation profile.
• Each object may contain all configured properties of this type, depending on the
setting of the query parameter (inline = true).
• The returned child objects collection only contains those that the user has
access to.
• Each type entry must contain link that point to a specific type.

Type
The type resource represents the configuration of a type in a specific
creation profile.

URI Template
/repositories/{repositoryName }/type-configuration/{typeId}?
profile={profileId}

29
repositoryName Name of the repository
profileId Object ID of the Creation Profile to which
this type belongs (mandatory)
typeId Object ID of the type

Link Relation

Link Relation Description


self Link to this type
type-configuration Collection of types that are defined as
part of this specific profile

Operations

Method Description
GET Retrieves properties, and other
information of the type resource.

Get a Type
Gets properties and other information of this Type. Properties are returned as
embedded elements in the response message body.

HTTP Method
GET

Server Accepted Request Media Types


None

Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

30
Request Body
None.

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the type configured in a specific D2
Creation Profile.

Templates
The templates resource represents the list of available templates for this
object.

URI Template
/repositories/{ repositoryName }/objects/{objectId}/ document-templates
repositoryName Name of the repository
objectId Object ID

Link Relation

Link Relation Description


self Link to the templates for this object.

31
Operations

Method Description
GET Retrieves the list of content templates
applicable for this object.

Get Templates
Gets the list of available templates for this object, the template properties are
returned as embedded elements in the response message body. Other information,
such as link to actual template, is referenced from the link relations of the response
message body.

HTTP Method
GET

Server Accepted Request Media Types


None

Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

32
Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the list of templates available for this
object.

Create Object Content using Templates


To create an object’s content based on an existing template. This operation is
performed on an already created object. When the object has no content attached to
it, the template is bound to the object. When the object already has content and is
of a compatible format to the template, then the template is attached. If the format
is incompatible, appropriate error message is provided.

URI Template
/repositories/{ repositoryName }/objects-d2/{objectId}
repositoryName Name of the repository
objectId Object ID

This URI template will be replaced with /repositories/


{repositoryName}/objects/{objectId}.
This will be done when the URIs from Core REST can be overridden.

Operations

Method Description
POST Specify the template name to be
attached to the object.

HTTP Method
POST

Server Accepted Request Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json

Query Parameters
None

33
Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
XML or JSON representation of the properties of template to be set on the object.

Example:
{ “properties”: {“template_name”: “AOP Document”, “folder_id”:”
0c01e2408004ee4e”}}

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Supported Response Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the object to which template was bound.

Preview URLS
The templates resource represents the list of available preview urls for
this object. BOCS/ACS and O2/C2 plugins are supported.

URI Template
/repositories/{repositoryName}/objects/{objectId}/preview-urls-d2
repositoryName Name of the repository
objectId Object ID

34
Link Relation

Link Relation Description


self Link to the parent object.
parent Link to the parent object

Operations

Method Description
GET Retrieves the list of preview urls
applicable for this object.

Get Preview Urls


Gets the list of available preview urls for this object, urls are returned as
embedded elements in the response message body.

HTTP Method
GET

Server Accepted Request Media Types


None

Query Parameters
Inline – Refer to: Common Definition – Query Parameters for more info.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
None.

Response Headers
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

35
Supported Response Media Types
• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json
• application/xml (For compatible viewing)
• application/json (For compatible viewing)

Response Status
200 - Information retrieved successfully
400 - Bad request; invalid property name or value
401 - Authentication failed
500 - Other unexpected server error

Response Body
This is a XML or JSON representation of the list of urls available for this object.

Configuration

Edit “settings.properties” file in “dctm-rest/WEB-INF/classes” path.


Define the D2FS server url.

connection.remote.url=http[s]://[proxy|server][:[port]]/[D2_Ctx]

36
C2 and O2 plugins installation

O2/C2 plugins are supported. Need to be manually installed.

C2 : Copy “C2-API.jar” and “C2-Plugin.jar” files in “dctm-rest/WEB-INF/lib” path.

O2 : Copy “O2-API.jar” and “O2-Plugin.jar” files in “dctm-rest/WEB-INF/lib” path.

Examples

Follow these steps after deploying Documentum D2FS REST Services:


1. Type the following URL in your web browser to navigate to the service
Define <docbase> and <id> by a valid value.
http://localhost:8080/dctm-rest/repositories/<docbase>/objects/<id>/preview-urls

JSON result :
{
"entries": [
{
"content": {
"links": [
{
"href":"http://<server>/d2fs-
rest/repositories/<docbase>/objects/<id>/preview-urls-d2/",
"rel": "self"
},
{
"href":"http://<server>/d2fs-rest/repositories/<docbase>/objects/",
"rel": "parent"
}
],
"url": "http://<server>/D2/servlet/Download?
uid=context_rest_XXXXXXXX&_docbase=<docbase>&_username=XXXX&_password=XXXXXX&_locale=en&i
d=<id>&format=pdf&event_name=d2_view_inline&c2_config_name=C2+QA+View"
},
"id": "http://<server>/d2fs-rest/repositories/<docbase>/objects/<id>/preview-urls-
d2/",
"links": [
{
"href":"http://<server>/d2fs-
rest/repositories/<docbase>/objects/<id>/preview-urls-d2/",
"rel": "self"
}
],
"title": "http://<server>/D2/servlet/Download?
uid=context_rest_XXXXXXXX&_docbase=<docbase>&_username=XXXX&_password=XXXXXX&_locale=en&i
d=<id>&format=pdf&event_name=d2_view_inline&c2_config_name=C2+QA+View",
"updated": "2014-08-25T15:36:22.882+02:00"

37
}
],
"id": "http://<server>/d2fs-rest/repositories/<docbase>/objects/<id>/preview-urls-d2",
"links": [
{
"href":"http://<server>/d2fs-rest/repositories/<docbase>/objects/<id>/preview-
urls-d2/",
"rel": "self"
}
],
"title": "Preview urls on object: <id>",
"updated": "2014-08-25T15:36:22.882+02:00"
}

If C2 is installed, check if “c2_config_name” parameter is present in the url.


If O2 is installed, check if “o2_config_name” parameter is present in the url.

Object Creation
Unlike Core REST APIs where the creation of objects happens within a
folder, in the D2 REST Server Space the object creation can happen at the
“repository” level. Created objects are automatically placed into the
user’s home directory or auto-linked to a specific folder depending on the
D2 configuration. Hence, the object creation URI template resides at the
repository level.
As in Core REST, objects can be created in one or two steps. In a single
step creation process, the objects are created by passing both content
and properties together. In a two-step creation, an object without content
is created and then content is attached to the created object.
While attaching content, templates can be bound as seen in the
Templates section. The other way to attach content is by using the link
relation: “contents” on the object. For more details on how to do this:
https://community.emc.com/docs/DOC-33250

URI Template
/repositories/ { repositoryName }/object-creation
repositoryName Name of the repository

Link Relation
All the link relations that is applicable for a newly created object. See
“Link Relation”, section in SysObject resource of the Core REST Developer Guide,
which provides information on what kind of links are available for a certain type of
object.

38
Operations

Method Description
POST Creates a new object

HTTP Method
POST

Server Accepted Request Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json

Query Parameters
None.

Request Headers
• Accept
• Authorization
• Content-Type
For more details about HTTP headers, see Common Definition - HTTP Headers.

Request Body
XML or JSON representation of the object to create.
• The object type is specified in the r_object_type property of the request body.
• Any other properties of the object can also be specified in the request body.
• The D2 Configurations that are applicable for this object creation is passed in
the request body along with other properties such as object_name.
• D2 Configuration will take precedence over supplied properties such as
object_name, folder_id if there are auto-naming rules and auto-linking rules specified.
• During creation – it is not possible to pass the template information; it can only
be set after the object is created. Reason: The lists of available templates that can be
bound to the object depend on the created object. Hence, template is not a valid d2
configuration during creation.
• In case of mulitpart, it is necessary to set the Content-type to multipart/form-
data; boundary=boundary_string. The boundary string acts as a separation between
the form-data and the content. Please refer to section: “Multi-part Request
Representation” of the Core REST Developer Guide.

Examples
• Creation of object without content:

39
{"properties":{"r_object_type": "bookpreview", "d2_configuration":
["start_version=2.2", "lifecycle=New lifecycle", "folder_id=0c01e24080000105"],
"object_name":"test.txt"}}

• Creation of object with content:

--91FJE9lOv7JqplS6Y_AYIoCtY2ePfQxPaiK
Content-Disposition: form-data; name="object"
Content-Type: application/vnd.emc.documentum+json; charset=UTF-8

{"properties":{"r_object_type": "dm_document", "d2_configuration":


{"inheritance_config ":"New inheritance",
"inherited_id":"0900304280007df9","inherit_properties":"true", "lifecycle": "Document
Life Cycle"}, "object_name":"test33.txt"}}
--91FJE9lOv7JqplS6Y_AYIoCtY2ePfQxPaiK
Content-Disposition: form-data; name="content"; filename="plain.txt"
Content-Type: plain/text; charset=UTF-8

This is a primary content sample with plain text!


--91FJE9lOv7JqplS6Y_AYIoCtY2ePfQxPaiK

Object Versioning
Objects can be versioned by the user who has sufficient permissions on
the object. In addition to the permissions, the D2-Configuration offers
configuration to place additional options and restrictions during the
checkin and checkout of the object.
As in Core REST, objects can be versioned by doing a checkout followed
by a checkin. The checkin can be a minor/major/branch/same version. The
checkout places a lock on the object which can be removed by doing a
cancel-checkout. The checkin request can be a POST request which posts
–a) text/plain – for content only, b)multi-part – for content and properties,
and c)JSON/XML – for properties only.
While doing a checkout/checkin the corresponding D2 configurations –
Checkin and Checkout config objects are read. The configurations are
honored by the D2REST services.

URI Template
/repositories/ { repositoryName }/ objects/{chronicleId}/versions?object-
id={objectId}&version-policy=next-major
/repositories/ { repositoryName }/ objects/{chronicleId}/versions?object-
id={objectId}&version-policy=next-minor

40
/repositories/ { repositoryName }/ objects/{chronicleId}/versions?object-
id={objectId}&version-policy=branch-version
/repositories/ { repositoryName }/ objects/{chronicleId}/versions?object-
id={objectId}&version-policy=same-version

repositoryName Name of the repository


chronicleId Chronicle ID of the object.
objectId Object ID

Link Relation
All the link relations that is applicable for a newly created object. See “Link
Relation”, section in SysObject resource of the Core REST Developer Guide, which
provides information on what kind of links are available for a certain type of
object.

Other Details
Please refer to the Core REST Developer Guide for more info as these link
relations are extensions from Core REST and they honor D2 Config. Sample steps
of how object can be locked, versioned are also present in the Guide.

Sample Steps
These steps describe how to perform common tasks in D2.

Viewing profiles, types


Follow these steps after deploying Documentum D2FS REST Services:
1. Type the following URL in your web browser to navigate to the service
node (Home Document).
http://localhost:8080/dctm-rest/services.json
The service node contains a list of the available services.

41
In the link relation http://identifiers.emc.com/linkrel/repositories, note the
URI to the repositories resource.
2. Click the repositories link you got from step 1 to navigate to the list of
all available repositories. Explore the output, and note the information in
the entries element.
3. Click the href link of the edit link relation of a repository in the entries
element to retrieve the details of the repository. Enter your credentials if
you are prompted for authentication.
By accessing the “href” values for the various link relations in the links
element, you can drill down various resources in the repository.

42
4. By clicking the “href” for link relation:
http://identifiers.emc.com/linkrel/profiles-d2 in the links section, you
can navigate to the list of available D2 Creation Profiles. This list is based
on the user’s context which is configured in D2.

Optionally, “inline=true” query param can be used for the complete entry
to be visible.

43
5. Alternatively, to view only a specific profile, navigate on the link rel:
“self” of an entry.

44
This response has link relations to point to the
a) Types present in this profile
b) A self-link pointing to itself (this profile).

45
6. To know the list of types configured in a profile, navigate to the “href”
of the link relation identified by:
http://identifiers.emc.com/linkrel/types-d2. Use inline=true to get
the type configuration along with the types. Otherwise, navigate on the
“self” link relation of each type entry.

As seen earlier for profile, each type has similar link relations to navigate
to:
a) the types which are present in this profile (types-d2)
b) self link (which is this type).

46
Content creation
There are 2 ways to create content:
A) Create Object without Content; attach content to the object (two steps)
B) Create object with content (single step)

Create Object without content


A) To create Object without content – Navigate to the href pointed by
linkrelation: http://identifiers.emc.com/linkrel/objects -d2.
Now, POST data such as below to create an object without content:

The "d2_configuration" section provides the list of configurations that are


to be applied to the created object. Note that these configurations need to
exist in the Docbase. Sample Response for the above request is shown

47
below:

Now, to set the content – follow the Core REST link relations or use
templates from D2.

To get the list of available templates for this object, follow the href for the link
relation:
“http://identifiers.emc.com/linkrel/document-templates”
The response contains information about the template and the URL to the actual
template document object.

48
To set content to the object without using templates, use the other link
relations “content”.

Create Object with content


To create Object with content – Navigate to the href pointed by
linkrelation: http://identifiers.emc.com/linkrel/object-creation.
Now, POST data such as below to create an object with content.
This content can be stored as a file in the local machine and the content-
type needs to be set as: multipart/form-data;
boundary=boundary_string.

49
This is similar to the earlier request; note that the “d2_configuration” is
passed along with the content.
The response obtained is similar to the earlier response.

C2-View & C2-Print


To support C2-View and C2-Print C2-plugin should be installed to the D2
REST Web application. Copy Manually C2-API.jar and C2-plugin.jar into the
D2 Rest Web War file.
URI Templates:
1) X_C2_VIEW_D2_URI_TEMPLATE : {repositoryUri}/objects/{objectId}/views/c2-
view
2) X_C2_PRINT_D2_URI_TEMPLATE: '{repositoryUri}/objects/{objectId}/views/c2-
print'

C2-View :
C2-View lists all the download URLS for the given object only if the object
has one PDF rendition , it lists down all the C2_View_configs configured in
the D2-Config which are applicable for the given document, then for each
c2_view_config it lists down the download URL.
Link Relation:
This new http://identifiers.emc.com/linkrel/views/c2-view link relation is
available to the object if the object’s content itself is PDF or it has at least
one PDF rendition available.
Eg :
<link rel="http://identifiers.emc.com/linkrel/views/c2-view"
href="http://10.31.168.68:8090/d2_rest/repositories/CSAUTO/objects/09003039
8005c5b2/views/c2-view"/>

50
HTTP Method
GET

Server Accepted Request Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json

Query Parameters
None.

HTTP Sample Request:


http://10.31.168.68:8090/d2_rest/repositories/CSAUTO/objects/090030398005c5b2
/views/c2-view

Sample Response for the above request is shown below:

<dm:url> : The download URL also lists BOCS/ACS URL based on the
following properties configured in d2fs.properties.
D2-BOCS=true
includeAcsServer=true

51
Note : we do not support Linked objects and Multi repository solutions as
it’s a limitation in CORE REST.
C2-Print :
C2-Print lists all the download URLS for the given object only if the object
has one PDF rendition , it lists down all the c2_print_configs configured in
the D2-Config which are applicable for the given document, then for each
c2_print_config it lists down the download URL.
Link Relation:
This new http://identifiers.emc.com/linkrel/views/c2-print link relation is
available to the object if the object’s content itself is PDF or it has at least
one PDF rendition available.
Eg :
<link rel="http://identifiers.emc.com/linkrel/views/c2-print"
href="http://10.31.168.68:8090/d2_rest/repositories/CSAUTO/objects/09003039
8005c5b2/views/c2-print"/>

HTTP Method
GET

Server Accepted Request Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json

Query Parameters
controlled_field_1
controlled_field_2
controlled_field_3.

HTTP Sample Request:


http://10.31.168.68:8090/d2_rest/repositories/CSAUTO/objects/090030398005c5b2
/views/c2-print

Sample Response for the above request is shown below:

52
Workflow and Task related REST Services
List of REST End points related to workflow
Task List End Point:
http://{host}:{port}/d2fs-rest/repositories/{repositoryName}/tasklist?
inline=true
Http Method: GET
Description: Task List End point lists all the tasks of a logged in user, if
inline=true, the task response will include elaborated task description.
Note : Task response is not capturing Workflow participants information or
Workflow Delegation user list.

Task Status End Point:


http://{host}:{port}/d2fs-rest/repositories/{repositoryName}/ /processes/
{processName}/{processId}/{taskName}/{taskId}/status
Http Method: GET

Parameters:
processName: Name of the dm_workflow process
processId: r_object_id of the dm_workflow process
taskName: Name of the workflow activity
taskId: r_object_id of the dmi_queue_item

53
Description: Task Status End point provides the state of the workflow task.
Http Method: Post

Parameters:
processName: Name of the dm_workflow process
processId: r_object_id of the dm_workflow process
taskName: Name of the workflow activity
taskId: r_object_id of the dmi_queue_item

Description: Post method of Task Status End point allows us to perform


various operations on Task
1) JSON request body for Accepting a task
{
"properties": {
"action" : "acquire"
}
}
2) JSON request body for rejecting a task
{
"properties": {
"action" : "reject",
"comment": "test comment",
"next_task_id": "task id"
}
}

3) JSON request body for forwarding a task with sign-off intentions

{
"properties": {
“action" : "forward",
"comment": "test comment",
"next_task_id": "task id"
"signoff_login": "user name",
"signoff_password": "user password"
}
}

4) JSON request body for delegating a task


{
"properties": {
"action" : "delegate",
"user":"user name"

54
}

TaskNotes EndPoint
http://{host}:{port}/d2fs-rest/repositories/{repositoryName}/processes/
{processName}/{processId}/{taskName}/{taskId}/notes

HTTP Method
PUT

Server Accepted Request Media Types


• application/vnd.emc.documentum+xml
• application/vnd.emc.documentum+json

Sample request
{
"properties" : {"task_note" :"POST NOTE THROUGH REST SERVICE"}
}

Installation Guide
Follow below guidelines for deploying rest war depending on the app server.

WebLogic 12.1.3
Disable web service annotation scan for WebLogic

Append below line to Java options of WebLogic startWeblogic.bat file.


-Dweblogic.servlet.DIDisabled=true

Since WebLogic has service provider hook for jaxb implementation ,duplicate implementations for jaxb related jars
results in linkage error. We need to follow manual changes to lib folder

Remove following jars from lib folder of deployment war.

jaxb-api-2.1.jar
jaxb-impl-2.1.6.jar
jsr173_api-20060801.jar
stax-api-1.0-2.jar
stax2-api-3.1.1.jar
xml-apis-1.3.04.jar
xmlParserAPIs-2.6.2.jar

Download below jars and add to lib folder

http://central.maven.org/maven2/com/sun/xml/bind/jaxb-impl/2.2.11/jaxb-impl-2.2.11.jar

55
http://central.maven.org/maven2/xalan/xalan/2.7.0/xalan-2.7.0.jar

WebSphere Installation instructions

1) Manually remove 3 following jars from d2fs-rest-web.war/lib folder


a) javax.servlet-api-3.0.1.jar
b) xml-apis-1.3.04.jar
c) xmlParserAPIs-2.6.2.jar

2) Change the class loader order at Enterprise Applications > d2fs-rest-web_war >
Manage Modules > d2fs-rest-web.war

class loader with local class loader first (parent last)

References
• Core REST Developer Guide:
https://support.emc.com/docu51005_Documentum_Platform_REST_Services_
7.1_Development_Guide.pdf?language=en_US
• Content creation:
https://community.emc.com/docs/DOC-33250
• Core REST Extensibility :
https://iigwiki.corp.emc.com:8443/display/CMAAT/CoreExt+-
+Tutorial+of+Custom+Resource+Development

56

You might also like