Exploring Documentum RESTful Services – Part 2
I originally published this post to the Early Access Area for Documentum RESTful Services.
In the second part of my exploration of Documentum RESTful Services I promised that we’d delve into browsing around the docbase. Rather do that with ruby I thought I’d grab a copy of JQuery and have a look at what it takes to access the services using what is an increasingly popular javascript library. The most important part of delivering on this is the JQuery call:
$.getJSON(path, ...);
The important thing here is that because of concerns about cross-site scripting we can only call local paths. While getJSON allows remote paths now with the help of JSONP style callbacks, those require server side cooperation to work. I don’t know that they’re not implemented in Documentum RESTful Services, but flipping through the documentation I couldn’t find anything of that nature.
Rather than creating a War for one html file, I decided to show off nginx. Nginx is a superb webserver, and more importantly in this case, a reverse proxy. It has gotten a lot of attention in the Ruby on Rails community, which is where I fell in love with it. After grabbing a copy of nginx it’s simply a matter of doing a minor adjustment to the nginx.conf file.
location /resources {
proxy_pass http://127.0.0.1:8080/resources;
}
This will mean that anything below the /resources directory on our webserver is passed off to the tomcat instance on 8080. We can start nginx, and discover it works perfectly. Now that we can use just a path to reference the services, lets get started. We start with a fairly blank html file:
<html>
<head>
<script type="text/javascript" src="jquery-1.3.2.js"></script>
<script type="text/javascript">
// we will add our javascript code here
$(document).ready(function() {
// do stuff when DOM is ready
});
</script>
</head>
<body>
<div id="results"></div>
</body>
</html>
Notice the included jquery.js, the call the $(document).ready, and the results div. We’re going to use the call I mentioned earlier ‘getJSON’ to populate the results div with the results of calling the ‘folders’ resource with no arguments. Lets look at the code.
$.getJSON("/resources/core/repositories/test_repo/folders.json", function(data){ $.each(data.dataPackage.dataObject, function(i,item){ $("#results").append(item.properties.object_name+"<br/>"); }); });
If you put the above html file in the right place and run the example you’ll be prompted for the password, just like you would if you actually went to the resource endpoint itself, then you’ll see a nice list of the root cabinets. Suppose we want to more than just display the root cabinets though, that we want to use the returned results to allow us to click around the docbase. Here is an example that does just that:
It’s very rough, and doesn’t take into account many variables, such as relationships that are returned aren’t necessarily folders. But it does illustrate the ability to access Documentum using libraries like jQuery now.
Exploring Documentum RESTful Services – Part 1
I was chatting to Craig Randall on twitter a little while back and he let me know that they were just about ready to go into Early Access for their new web service platform - Documentum RESTful Services. I was excited then, and I’m even more excited now that I’ve had my first taste.
RESTful web services are hard to explain to people. I usually fall back on explaining them by linking them to Ajax, which is a Web2.0 technology that people are more familiar with. If you wanted to use Ajax to make your Documentum webapps more friendly before Documentum RESTful Services, then you’d be out of luck (short of creating a custom server side component).
RESTful web services are easily accessible because you don’t need any funky client library to access them. Pop open any web browser and type in:
http://localhost:8080/dctm_rest/resources/core/repositories/<RepoName>/folders
And you’ll get back an XML representation of all the root folders (after you’re prompted for a username/password). RESTful web services use only standard HTTP, which means that you’re cutting out the middleman of having to encode requests/responses in Soap (or some other container).
They’re automagically more language agnostic. Gone is the need for a complex client side library. For example, while it should strictly be possible to access DFS in any language, this doesn’t translate into a reality. So Documentum RESTful Services will allow us to step away from relying on Java/.Net and expand into using high level dynamic languages (python, ruby, javascript).
Let’s do a simple example in Ruby to demonstrate:
require 'rubygems'
require 'httparty'
class DctmRest
include HTTParty
base_uri 'http://localhost:8080/dctm_rest'
def initialize(username, password)
@auth = {:username => username, :password => password}
end
def repositories
options = { :basic_auth => @auth }
repository = "test_repo"
self.class.get("/resources/core/repositories.json", options)
end
end
d = DctmRest.new('username', 'password')
puts d.repositories.inspect
The example is probably more complex than it even needs to be. If I look at the output:
{"repository"=>[{"queriesUri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo/queries.json", "repositoryType"=>"managed", "typesUri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo/types.json", "foldersUri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo/folders.json", "checkedoutUri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo/objects/checkedout.json", "uri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo.json", "name"=>"test_repo", "objectsUri"=>"http://localhost:8080/dctm_rest/resources/core/repositories/test_repo/objects.json"}]}
I can see a very succinct set of other URIs that I can use to get other information. In the next post I’ll go through how to browse around a Docbase using Documentum RESTful Services. For now, take the time to sign up for the early access program, so you can help give feedback on what is a giant leap forward for Documentum in the web2.0 world.
Installing Documentum Administrator 6SP1 (Patch Release) on IBM Websphere 6.1.0.23
I’ve spent the majority of the last 2 days trying to get DA 6SP1 Patch Release to install properly on IBM Websphere 6.1.0.23. It had been a while since I’d last done the install, and I fell into the same traps as last time, forgetting where to set the class loader and so forth. After getting past these I was left with the application unhelpfully still showing a white screen and error messages that revealed (looking back) very little about the true nature of the problem. Having finally conquered the problem, I thought I would provide the steps necessary so that anyone else trying to get a WDK application working on Websphere as at least one more thing to try.
Grab a copy of da.war from the EMC Powerlink Download site.
- Unpack da.war and add the following files to a directory
- Put dfc.properties into WEB-INF/classes (As described in the deployment guide)
- ibm-web-ext.xmi & ibm-web-ext.xmi goes into WEB-INF – https://solutions.emc.com/emcsolutionview.asp?id=esg91105
- Find a copy of xml.jar on the Websphere App Server in ‘Websphere\AppServer\java\jre’ and put in ‘WEB-INF\lib’ - https://solutions.emc.com/emcsolutionview.asp?id=esg93106
- Install the application using the IBM Administration Console.
- Change the order the classes are loaded in by expanding the Applications node and click the Enterprise Applications node. Select the application called da_war (or equivalent wdk app). Click the Manage Modules link. Click the da.war link. In the Class loader order drop-down list, select the option ‘Classes loaded with application class loader first’ – https://solutions.emc.com/emcsolutionview.asp?id=esg93177
- You can then save and start the application.
The xml.jar file is appropriate for D6SP1 only, previous D6 versions have a slightly different set of instructions (see linked support note). Any feedback, corrections, suggestions greatly appreciated.
ActiveDocumentum teaser #1
Having stepped away from trying to get Documentum running on linux, I’ve been working on bringing the permissions through into our custom Lotus Notes/Documentum client. At the moment when a user imports a document to a given folder it does no permission checking before the fact, just errors nastily when it can’t write the document. A short stop by Prasad’s blog gave me a query to start from.
SELECT i_all_users_names as users FROM dm_group
WHERE group_name IN (SELECT r_accessor_name FROM dm_acl
WHERE object_name IN (SELECT acl_name FROM dm_sysobject
WHERE r_object_id = '0c0xxxxx80009e16'))
ORDER BY i_all_users_names
This is superb, but it doesn’t actually go far enough. If I was to attach it to my application and tell it not to let me import anything into the folder if my name wasn’t on the list I wouldn’t be able to copy anything into my home cabinet. It enumerates the members of any group within the ACL but doesn’t deal with named users & also the owner.
This will give me a chance to show off what you can do with my ActiveDocumentum project. ActiveDocumentum is a working name for a JRuby gem written to provide functionality similar to what can be found in ActiveRecord, with the addition of repeating attributes and other DQL specific items. While the final code for the below function may end up being in Java or .Net. Doing it using ruby allowed me to very quickly scope out the logic of what would need to be done to get the permission that a user had on an object (NB: If there is a way to do this simply with DQL I’m not aware of it):
require 'config/environment'
def get_effective_permission(r_object_id, user = nil)
return 0 if user.nil?
folder = DmFolder.find(:first, :columns => "owner_name, owner_permit, acl_name", :conditions => {:r_object_id => r_object_id})
current_level = 0
if folder.owner_name.eql? user
current_level = folder.owner_permit
end
acls = DmAcl.find(:all, :columns => "r_accessor_name, r_accessor_permit, r_is_group", :conditions => "object_name = '#{folder.acl_name}' ENABLE(ROW_BASED)")
acls.each do |acl|
if acl.r_accessor_name.eql? user
current_level = acl.r_accessor_permit if acl.r_accessor_permit > current_level
elsif acl.r_is_group.to_s.eql?('1') and not acl.r_accessor_permit.nil?
group = DmGroup.find(:first, :columns => 'r_object_id, i_all_users_names', :conditions => {:group_name => acl.r_accessor_name})
current_level = acl.r_accessor_permit if acl.r_accessor_permit > current_level and group.i_all_users_names.include?(user)
end
end
end
return current_level
end
r_object_id = '0c0xxxxx80009e16'
user = 'John Doe'
puts get_effective_permission(r_object_id, user)
As you can see the above function takes a user and returns the highest permission that they have, by checking if they’re either directly listed on the ACL or in one of the groups on the ACL. The bottom line is that with ActiveDocumentum I can write less lines of code for one off scripts that I have to create, and include complicated logic that is lacking in straight DQL scripts. I will be posting more details on this in the near future.
D6.5 Experiments (Part 2)
I’ve been trying to do an install of Documentum using the Linux/Oracle downloads without much success. This may well be more on the Oracle side of the fence, but this started when I put Oracle XE(10.2.0.1-1) on a newly installed CentOS 5.3 virtual machine, and then tried to get Documentum (6.5SP1) installed and configured, only to get the majority of the way through and be told that the minimum is Oracle 10.2.0.3, despite what the release notes say.
Since 10.2.0.1-1 is the latest Oracle XE, I concluded that it must not be supported and moved on to trying 11.1 (Standard One). The biggest downside to this is that this Oracle installer is far less friendly than the XE installer, and at the end of it, I am not left with a TNSNAMES.ORA which Documentum needs. I am not an Oracle expert by any means, I would prefer to use PostgreSQL or MySQL, but they’re not a supported configuration. Even ignoring ‘supportability’, since this project is only experimental anyway, there is no information on whether it is even possible to get it running using these databases. Since there is a large amount of mapping/optimization between DQL and the underlying SQL I would tend towards it not being possible.
Does anyone have any advice or instructions for getting D6.5SP1 installed from scratch on linux? Failing that I will persist with my attempts, and let you know how it turns out.