Decoding xperms

Object permissions are stored as integers in Documentum ACL objects. For each accessor, there is one value (1-7) which represents one of None, Browse, Read, Relate, Version, Write, and Delete. These permissions are hierarchical, so 4 would imply 4 and everything below it.

ACL’s also include extended permissions. An accessor can be assigned a subset of Change Location, Change Ownership, Change Permission, Execute Procedure, Change State, and Extended Delete. All of these values are independent and they can be assigned in any combination to one accessor in an ACL. However, there is only one field to store the extended permissions for one accessor. The obvious way to store such information is using bit fields and, indeed, that is how it is stored in the repository. There is only one catch though – the details are hard to find until you hit the DFC Javadocs for IDfACL. There you can find the specs under the method getAccessorXPermit().

You would think that that’s the whole story but it isn’t. It’s very easy to get it wrong like this post did. The bits at position 0 and 1 are interpreted in a reverse manner compared to the rest of the bits – 0 means has permission and 1 means doesn’t. That is why “no extended permissions” is encoded as 3!

That’s about it. The only additional piece is that D6 has added a new extended permission – Change Folder Links. The Javadoc for bit-encoding hasn’t been updated to reflect this change. However, it will be pretty easy to figure out by dumping an ACL object containing that extended permission.

[UPDATE] Here is the obvious way to implement it using the bit-wise AND operator (&).
// assuming that R_ACCESSOR_XPERMIT contains the integer value to be decoded
boolean execProc = (R_ACCESSOR_XPERMIT & 1) == 0;
boolean chgLoc = (R_ACCESSOR_XPERMIT & 2) == 0;
boolean chgState = (R_ACCESSOR_XPERMIT & 65536) != 0;
boolean chgPerm = (R_ACCESSOR_XPERMIT & 131072) != 0;
boolean chgOwner = (R_ACCESSOR_XPERMIT & 262144) != 0;
boolean extDelete = (R_ACCESSOR_XPERMIT & 524288) != 0;


And just for fun, here is another way to implement this decoding without using bit-wise operations. The % is the mod operator which takes the remainder after division.
// assuming that R_ACCESSOR_XPERMIT contains the integer value to be decoded
boolean execProc = (R_ACCESSOR_XPERMIT%2) == 0;
boolean chgLoc = (R_ACCESSOR_XPERMIT%4) - (R_ACCESSOR_XPERMIT%2) == 0;
boolean chgState = (R_ACCESSOR_XPERMIT%131072) - (R_ACCESSOR_XPERMIT%65536) != 0;
boolean chgPerm = (R_ACCESSOR_XPERMIT%262144) - (R_ACCESSOR_XPERMIT%131072) != 0;
boolean chgOwner = (R_ACCESSOR_XPERMIT%524288) - (R_ACCESSOR_XPERMIT%262144) != 0;
boolean extDelete = (R_ACCESSOR_XPERMIT%1048576) - (R_ACCESSOR_XPERMIT%524288) != 0;


Who Owns this Repository?

You need to figure out the repository owner for a repository. What do you do?

Guess, it’s dmadmin. Well, dmadmin is the conventional installation owner. Indeed, it is possible that there is no user named dmadmin in a repository.

So, maybe use the installation owner – the user id on OS used for installing the Content Server. Well, installation owner is separate from repository owner and there is no requirement for the two to be the same. Actually, they should be kept separate – in many organizations installation responsibilities are separated from day-to-day administration responsibilities.

Hmmm, is it same as the repository name? Maybe. When you configure a new repository, you have a choice to set up the database beforehand or to let the configuration script set it up for you. If you let the script do this work, it defaults the DB account to be the same as the repository name. In this case, this guess would be valid. However, it is not required to be so. If the database is already set up, you can provide this information to the configuration script and it uses the provided DB user to create the corresponding user in the repository. This user becomes the repository owner.

Then, is there an attribute on dm_docbase_config which identifies the repository owner? We are getting close. There isn’t an attribute called docbase_owner or repository_owner. However, the owner of the docbase config object (identified by owner_name) is the repository owner. If you are looking for the exact DB login name for the repository owner then look at the user_db_name attribute on the user object for the repository name. For the repository owner, it is same as the user_name by default.

Also, the operator_name on a dm_server_config object defaults to the repository owner name. Remember that this is just a default. Further, there can be multiple content servers serving one repository.

Check in as Same Version?

Webtop lets you check in a document as the same (existing) version. However, when you do this the Content Server never sees a checkin call or event. Webtop simply sets the new file as content, updates any changed attributes, and saves the object. So a dm_save event occurs rather than dm_checkin.

It becomes more obvious if we look at the corresponding API call descriptions.

• checkin – creates a new version of an object in the repository and removes the lock from the previous version.
• save – writes the object to the repository without creating a new version of the object.

Both of these methods have an optional argument to retain lock on the resulting object (new version for checkin and existing version for save). This argument defaults to FALSE – the lock is gone after the operation.

So why do we care? Normally we don’t need to. However, if we turn notification on for a document we need to remember this difference between checkin and save. By default, notifications are sent only for checkin event occurrences. So we won’t get a notification if the document was “checked in as same version”.

Similarly, other behavior (such as auditing) tied to events may be affected.

Uprooting a Version Tree!

What happens if the root version (1.0, one whose object id is same as its chronicle id) in a version tree is destroyed? It is an important object and may be referred to via the chronicle id of the other objects in the version tree.

In this situation, Content Server does not remove the object from the repository. Instead, it marks the object as deleted (i_is_deleted=TRUE) and removes its associated objects from the repository. The server also unlinks the object from all cabinet/folder locations and places it in the Temp cabinet. If the object is current (has version label CURRENT), it moves that label to the last modified version in the tree (highest r_modify_date).

More information on destroying objects can be found in the Content Server Fundamentals guide.

Documentum Installation Owner and Windows Services

Documentum installation owner user id is used for installing Documentum Content Server. On Windows, the installation sets up services for each repository (docbase), connection broker (docbroker), and Java method server. If you run into issues related to the installation owner id (typically authentication related), there are two aspects that can be checked:

1. Each repository service has an associated command-line which specifies the installation owner as an argument. This command-line is visible on service properties when inspected through Windows services. You can edit the command-line through Documentum Server Manager utility. Select the relevant repository and click on the Edit Service button.
   1. Note that this argument overrides the install owner specified in server.ini in case there is a conflict between the two.
2. All the windows services use logon credentials and the Documentum services mentioned above use the installation owner credentials. These can be edited through the standard Windows service properties dialog.

Inspecting Documentum Repository Service

Issues related to the installation owner may arise when it is a domain user (as opposed to a local user) and/or when multiple content servers are being used. Another aspect to remember is that while Windows treats the user id as case-insensitive Documentum treats it as case-sensitive. Repository configuration also creates a user in the repository for the installation owner, using the exact case as entered during the installation process (at login time prior to installation).

Handy DQL: Count Objects by Month or Year

There are times when you want to count objects by month or year for a date attribute. The following DQL shows how to count objects of type dm_document by the month of their creation using the DATETOSTRING function.

select DATETOSTRING(r_creation_date, 'yy/mm') as period, count(*)
from dm_document
group by DATETOSTRING(r_creation_date, 'yy/mm')

You can add a where clause as usual if you want to add conditions to the query. You can also play with the date format but know that some format strings may not work as you might expect them to.

What’s in a name?

Quite a bit if you are a Documentum user.

Documentum uses the user_name attribute of dm_user for uniquely identifying a user. This means that permissions and object ownership are also assigned to a user using user_name. Rajendra discusses various drawbacks of this design choice. One of the comments also indicates the reason why r_object_id wasn’t used as the key – the LDAP Sync job would sometimes delete and recreate the user object and creating a new object id in the process.

I have also been asked why wouldn’t one use the login ID as the key. I don’t have an authoritative answer but I have some thoughts around the difficulty of doing that in Documentum. First note that there is a user_os_name attribute as well as a user_login_name attribute. These are expected to be unique only in combination with user_os_domain and user_login_domain respectively. The attribute user_ldap_dn is relevant only when an LDAP server is being used. The population of these attributes is tied to the authentication mechanism in use, which could even be a custom plugin.

That leaves us with really one good option for the key – r_object_id, provided the object id wouldn’t change for a user. However, that’s not the case currently.

So why should you care? Check Rajendra’s post if you didn’t earlier when it was mentioned above. My experience has been more around presence of commas in the user name. It is not handled robustly across the platform. Even though problems are fixed in various service packs, they seem to be scattered across architecture layers. I shared an issue with the queue() call in another post.

More recently, I encountered another issue. In 5.3 SP5, if you enable dmcl trace in a WDK app (using wdk/dmclTrace.jsp) the log file name is generated using the name of the logged in user as a prefix. If the user name contains a comma, the portion of the name is stripped up to the comma. The resulting log file name is not accepted by some other piece of code, which apprently expects the log file name to begin with the user name. Yes, you can specify an explicit log file name but it tries to generate the log file mentioned above anyway.

The takeaway is to treat the user_name attribute like a key – use simple characters and if you have a choice maybe store the login id from your authentication source into the user name attribute. More likely you already have a deployment – in that case, arm yourself with the knowledge of these issues so that you can tackle them successfully.

The Fundamentals Trap for Documentum Professionals

Over the last couple of months I have frequently noticed myself referring to a personal experience. It was a rude awakening that ended up influencing my career considerably – upwards, thankfully!

After leading and completing several Documentum projects I was very confident about my ability to implement Documentum solutions. So when I interviewed for a position and failed the phone screen, it was a rude shock! Initially, I was in denial. I blamed the interviewer – he was a non-technical manager who was asking technical questions from a list and expected the exact answers that were given to him. Gradually, I accepted the fact that I didn’t know several fundamental concepts well, even though I could look them up any time I needed and would grasp them without a problem. I had learned well by doing but that had left much to be discovered. I could put in several more years to learn purely by experience or I could take a deep dive into the fundamentals and educate myself. I chose the latter and I am so glad I did.

Fast forward to today. One certification, an online community, and a book later I find myself on the other side of the phone. I often help my clients when they need to hire Documentum professionals. I notice the excitement when they see a resume reflecting 3-4 years of Documentum experience with aspects relevant to their needs. On the phone, it is a different story though. A self-described Documentum Architect cannot describe the solution architecture for projects on his resume – because there was another team that handled infrastructure. A self-described Documentum Administrator can explain little beyond creating users and adding them to groups – what else is there to Documentum administration? Oh yes, jobs. Which jobs do you know about? dmClean. What does it do? Cleans up docbase. Or deletes objects. Some get to “remove orphan objects”. What is an orphan object? Either a blank or cook something up. How can you find out where the content file for an object is stored? Content Server! It’s an attribute on the object. Some get so far as the content object but struggle to relate it to sysobject well. These are just some examples. Some candidates even get annoyed as to why they are being asked such fundamental questions (never mind that they don’t know the answers).

Most of these candidates probably do their tasks well and use the reference wisely as needed. But the interview experience does little to reassure the person who will be writing some not-so-lean checks for this position. The supply-demand inequation for Documentum professionals probably lets Documentum-experienced professionals persist in this mode because Documentum-skilled ones can’t be found within the timeframe, location, or other constraints.

I often share my experience with the candidates that I pre-screen hoping to help them take it in stride and maybe to inspire them to take a good next step. Some take it while others don’t get it. Oh, well.

Going beyond the interviews, a good grasp of fundamentals has helped me with better design decisions, including catching some would-have-been-mistakes before they happened. I strongly recommend taking the technical fundamentals exam (or just preparing for it if you don’t believe in certifications). Use the free resources such as dm_cram to help you in your pursuit.

If this topic interests you, Pie has an interesting discussion going on about career vs. job in Documentum. Sumanth has also discussed some of his hiring experiences.

Good luck with the step up your career curve!