REST services in Documentum

By | 2018-06-13T11:21:55+00:00 February 5th, 2014|Documentum, REST Services|2 Comments

With the introduction of Documentum 7 EMC added REST services to their set of webservices. Of course they already had a set of SOAP webservices with their DFS framework. However in some cases people might prefer a RESTful webservice over a SOAP one and EMC seems to be one of those people as you see it being used more and more often. There are even rumors going on that the SOAP webservices might be removed from the product in the future but I don’t think this has been confirmed yet.

They also released a set of REST webservices you can use for yourself called “Documentum REST Services” and I decided to give them a try.

Introduction to REST

For the people who don’t know REST or who don’t know the difference between REST and SOAP here’s a short introduction. The biggest advantage of REST over SOAP is that it’s usually using the HTTP protocol which means you can call the webservice from your browser. Type the url of the service in your browser and you will see what content the webservice will give back (only in case of a GET request of course). This makes the webservices really easy to test but also really easy to use in your application.

Also there is a small performance increase if you compare it to SOAP which may of course help you when doing really large operations.

On the other side REST doesn’t really have an official standard yet. It can be implemented in many ways whereas SOAP has an official standard and defines the way client and server communicate by enforcing it through a WSDL file.

Installing Documentum REST Services

When you download the Documentum REST Services you only get a war file which needs to be deployed on the application server. You can use the same application server that you used for DA or DFS. The only thing you need to do is edit the dfc.properties file in the WEB-INF/classes folder. After that you are ready to go.

You can test if the deployment was successful by browsing to the following url: http://{server}:{port}/dctm-rest/services

First thing to notice here is that you can always choose if you want XML format to be returned or JSON format. There is no real advantage in using either one. JSON is a little bit more compact which may help you with performance a little bit. XML is easier to read and might help you develop a little bit faster. Just choose whichever you like better. If you want the json format to be returned just add .json to the end of the url: http://{server}:{port}/dctm-rest/services.json

A better test is probably to get a list of all your repositories: http://localhost:8080/dctm-rest/repositories/ .If this url gives a list of all your repositories you are good to go.

Available REST services

The REST services packages comes with a pretty big set of webservices you can use. I am not going to name all of them but I will discuss a small set of them.

Object services

There are quite some webservices that help you to interact with objects in the docbase. You can get lists of all sorts of objects (per folder, objects that are checked out, version per object etc).

They also give you the ability to create a new Object by using the POST method.

User services

These services help you to get lists or properties of (a) user(s). This is also the same for groups. You can retrieve all sorts of groups (groups in group, users in group etc). However there is no option to create new users or groups.

Relations

Since relations have become more important in xCP2 it is nice to have a webservice that help you with retrieving those. You can even create new relations if you want.

DQL

There’s even a DQL webservice. Just tell it which query you want to run and it will give you back the objects with its’ properties.

Developing your REST application

Before I start, I really advise you to use FireFox with the firebug extension (or something similar) installed when developing applications like this. Firebug displays javascript erros, httprequest, the response of the httprequest and the DOM. All those things makes it a lot easier to troubleshoot and develop your application.

Of course there are countless ways to call a REST service. I was particularly interested in calling a REST service from javascript as this is a really quick and easy way of developing an application. Another advantage is that if you use javascript you can really easy package it in a library and import it into your xCP2 application.

I created a new web application on the application server and started from there. Now you can call a webservice in plain javascript by doing an xmlHttpRequest. However this requires a lot of code and some try catch loops, plus there are some really good libraries to help you with this. Best option would of course be extJS since xCP2 uses this. However since I’m not that familiar with extJS and am really familiar with jQuery I decided to use jQuery.

in jQuery you can do a request by using the $.ajax function:

[code]

var url=”http://localhost:8080/dctm-rest/repositories/acme/cabinets.json”;

var jqxhr = $.ajax(

{

dataType: “json”,

url: url

})

.done(function(msg) {

writereps(msg);

})

.fail(function(jqXHR, textStatus, errorThrown) {console.log(errorThrown)});

[/code]

First you specify what the url is of the webservice that you are going to call. In this case I wanted to know which cabinets are in my repository so I called the /repositories/[repositoryname]/cabinets.json webservice.

Next you do your ajax call. You tell it what the datatype is that is being returned (either json or xml) and the url.

Then you specify what needs to be done when the call is finished. In this case I’m calling another javascript function called “writereps”. The variable “msg” being given to the function represents the response of the webservice. If you want you can also specify what has to be done when the call fails. This is optional but it might help you troubleshooting when something happens. In this case I log the error to the console.

Now that you have your webservice response you can do with it anything you want. In this case I wanted to display a list of all the cabinets in the repository:

[code]

function writereps(msg)

{

var cabinets = msg.entries;

var s = ‘<h1>Cabinets</h1>’;

for (var i = 0; i < cabinets.length; i++)

{

var cabinetName = cabinets[i].title;

var url = cabinets[i].id;

var li = url.lastIndexOf(“/”);

var id = url.substring(li+1);

s += ‘<span onclick=”retrieveContent(\”+id+’\’)”>’+cabinetName+'</span>’;

s += ‘<br>’;

}

$(‘#cabinets’).html(s);

}

[/code]

I won’t go into too much detail here but one thing I noticed is when I wanted to know what files are in the cabinet is that there is no element for the r_object_id. A lot of the other webservices are based on the r_object_id so you can use this to construct your other url’s. However since that was not present I extracted it from the ID element (which is an URL).

Conclusion

The Documentum REST services work exactly the way I expect them to work. They return the data in an easy and quick format and I can use it for all other activities.

The set of services provided is extensive enough to write your applications. I’m really curious however how it will handle content (documents) as I know REST has some limitations in that area. If somebody has some experience in that area please let me know.

2 Comments

  1. Jed Spink February 6, 2014 at 11:54 pm - Reply

    Just to note that REST is available for Content Server 6.7 onwards, not just v7 as per your opening line as stated towards the end of this article.

    https://community.emc.com/community/edn/documentum/blog/2013/06/22/announcing-emc-documentum-rest-services-70

Leave A Comment