Users, Groups, and Roles with ACLs and Presets

At some point in the evolution of any repository’s design and implementation, the issues of managing users, groups and roles, and of reducing object type clutter rise to the top of the priority list. Also, finding a common way in Webtop of displaying attributes for documents listed in folders and search results becomes vital to maintaining a consistent user experience and getting a grip on endless customization costs.

You can talk to the business about users, groups, and roles, but the ramifications of your design will not click with them until they see Webtop in action and what presets and ACLs are actually doing to their user experience. For example, a user has the ability to import content and as the owner of the content they can promote it even if they have Read access only: this is hard to understand unless it was shown during a demonstration.

Here are some tips on how to design and implement users, groups, and roles with ACLs and presets:

Manage User Group Membership from LDAP or Active Directory Groups
I strongly recommend managing group membership using LDAP integration, otherwise you’ll have to run a script to add members to groups the first time and then manage group membership one by one with Documentum’s tool instead of a more robust user directory tool management tool.

Either use or exclude the dm_world default group from accessing your content
For tighter control of security, create a custom group that is your company’s base group from which to build. This base group should have a consistent level of minimal access to all content in the repository, such as Read access.

Using Presets to reduce Action in Webtop
Now that you have a base custom group, you can exclude from that group any actions, such as “Create New Documents” or “Import” from Webtop. Review the manual on what the basic client capabilities of Consumer, Contributor and Coordinator are before trying to add these to Presets.

Create Test Users that have Inline Passwords, as well as Users from LDAP and Local Domain Users
Sometimes LDAP will be “slow” or “failover” (I know User Directories never fail, but they do and you need to be able to access the Repository when and if it ever does. Chances are that your install owner account (“dmadmin”) will be a local account (I hope). So if domains or LDAP or the network is down at least you’ll be able to access the repository with inline or local accounts.

dmadmin: superuser best practice
- Add docu group as delete, full privilege to all ACLs
- Don’t include docu with the custom world group
- Don’t use dmadmin to test
- Don’t have dmadmin in any other groups, especially ones controlled by presets because the link to Webtop administration of presets may vanish and you’ll have to create or move a new user into the preset group.

Create contributor Roles that are responsible for importing and creating new content for each group of content types
For a financial company, this means create a group for Tax, Treasury, Marketing, Operations, Accounting, and so on. Each group is responsible to for a certain group of content, for example, Tax imports tax returns, withholding docs, etc and Treasury has capital calls and distributions.

Create Presets for each Role that include the content types they import only
This controls the object type dropdowns when importing, checking in, and creating new content from templates. Be sure to include a parent type that will not be used, but will be the first in the dropdown, so that custom attributes will be refreshed when the custom type is selected from the dropdown.

Scope Search Object Type Dropdown by Object Type Parent
Users of Webtop usually need to limit the amount of object types to search for in advanced search. There’re only so many types that users need to look at for searching. Less is more in the case of the advanced search object types.

Scope Object and Doc Lists by Role
The display of custom attributes in the columns of search results and when browsing folders should be customized by Role to establish consistency and attribute value listing expectations. Custom attributes will be the important ones to show and sort in these circumstances.

For searching across all object types think about replication
First, you’ll need to figure out the common attributes across all of the object types. Second, although you might be able to roll up a few of the custom attributes into the parent type, different user interface requirements will probably force the design to repeat certain attributes in every child object type. One solution is to develop a TBO that replicates some of these common child attribute values to the corresponding parent attribute in order to search for them from the one parent object type in advanced search.

Composer the Poser

When a teenager wears skateboarding shoes and a brand named hoody but doesn’t skateboard, he is referred to by real boarders as a “poser”. Unfortunately, the same can be true for EMC’s Composer. It wears all of the key features of the doc app builder, but it ain’t no DAB.

Don’t get me wrong, like a good EMC citizen, using a DAB built system, I created Composer projects from Production to QA and Dev. I worked through some initial bugs in the Composer build and was determined to deploy the next phase of the project using D6 sp1 Composer. I had heard that D6.5 was not going to use DAB, so I thought I’d better get on the bandwagon and get used to Composer.

I read through Jason Duke’s article on the Blue Fish site and was assured that I’d get through the process with a few issues, but no show stoppers. I figured out that all of the directory structures needed to be consistent in each environment. I also worked through a deployment plan for multiple, decoupled dar files for easier development coordination and implementation. I rewrote my design document to follow the new and “improved” configuration UI of Composer.

The first road block was value assistance for a query. The xml file created by Composer was missing the “complete_list = true” key/value pair for the query element. This meant that the dropdown was fixed at 20 pixels. EMC support sent a fix for webtop (not Composer) which fixed the width of the dropdown, but the dropdown graphic was the new look and feel graphic. This was glaringly bad for users to see. What were they thinking?

The second road block was that if you include groups and roles in the Composer project during deployment they will overwrite the existing groups and members if you don’t remember to change the install instructions each time. There is no global way to tell Composer to ignore existing artifacts, thus each time you deploy, you have to set the install option again for each artifact. When the project install fails which it will over and over again, you’ll be clicking and clicking. Bottom line is that this needs a lot of work for it to be production ready.

The third road block was that value assistance for query based dropdowns changes the rendering of the select box as compared to the fixed value dropdown. Hello, a customer can tell the difference between the two and won't like it. The fix is the go into DAB and save it again, but this is no excuse. Gotta wonder what level of regression testing was done...

After chasing a few more bugs with Composer D6 sp1, the patch came out, but that didn’t help much. Common sense won out and we’ve gone back to using DAB for deployment. As clunky as it is, at least it isn’t a poser. By the way, DAB was released for D6.5. Gee I wonder why?

LDAP Unwrapped

Every time I configure a Documentum repository for LDAP Synchronization I start out impressed with the new features that have been added to the latest version, but end up frustrated with the myriad of problems to solve to get the synch to actually work.

The first thing you have to do is download the latest bug fixes, to avoid what always happens to me: shagging after errors on EMC Developer Network and searching and searching and finally finding some reference to bugs and fixes. The ftp address for D6 sp1 fixes is ftp://dev_pre:qa5.grN6@ftp2.lss.emc.com/sustaining/Content_Server/6.0_SP/LDAP .

The appendix below lists the bugs that are currently fixed. These fixes will make the synchronization actual work if you have more than one configuration set up to run in succession.

Start with the User Directory
You need to engage the LDAP administrator in order to determine whether the group membership structure of LDAP and if it makes sense to use it, that is, are the groups setup with content management in mind or are they a mixture of file system security and ad hoc assignments.

Also, have the user accounts been setup consistently? For example, Active Directory works fine with accounts set up like “smith,john” and “smith.joe”, however Documentum throws an error while processing the “smith.joe” because of the period.

You’d think managing group membership from one source application is easier than from multiple applications, however decoupling LDAP groups with Documentum groups may be more practical given the differing purposes and rules within each application. The classification rules (driven in part by group/role definitions) for a content management system are usually different and definitely more robust than those of a file system.

Automatic creation of user’s cabinets from LDAP
It’s not obvious how to do this from the LDAP configuration form. From the LDAP Server Configuration Properties’s mapping tab you have to add the following:
- Property: default_folder
- Type: dm_user
- Map To: /${cn}
- Map Type: Expression

This mapping will create a cabinet for each LDAP user as they are added to the repository. The cabinet will be owned by the user and will be private to that user. This cabinet will be the user’s home cabinet.

Appendix: D6 SP1 LDAP Bug Fixes

Bug fixes in LDAP_DOCAPP_HOTFIX
153994 - Unable to create LDAP config object on AIX/BEA as it throws java.lang.NoClassDefFoundError (It applies to all OS/Appserver combinations)
153355 - The Diretory type property is nto properly set while creation of LDAP config object
153322 - DA hangs on the Mapping tab while creation of LDAP config object
151022 - Cannot create LDAP config object with out setting proper OU info
150397 - LDAP config object cannot pull the SamAccountName attribute in AD2000 and AD mixed mode
151570 - Cannot create proper LDAP config object

Bug fixes in D6SP1_dmldap_hotfix
145896 - When using "\" in the CN values for LDAP, the LDAP synchronization propagates the users to Documentum properly but group membership synchronization fails because of this special character.
149446 - LDAP Synch fails when using subtype of dm_user
151224,154269 - LDAP Users with apostrophes in their names (i.e Robert O’Leary) have been successfully imported to Documentum. However, due to the apostrophe in the user name a DQL query is failing.
149443 - LDAP Synch fails when mapped attribute is null on Directory server
154399 - LDAP Sync jobs tries to deactivate the user even though the user is not present in the docbase.
154511 - If dm_ldap_config is to configure to map LDAP attributes to DocBase attributes of a subtype of dm_user, running LDAP sync failes to populate the additional attributes introduced in my subtype with LDAP data.
154704 - LDAP Sync throws DmLdapException:: THREAD: [ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)'; MSG: home_docbase - Property not found; ERRORCODE: ff; NEXT: null
155432 - The LDAPSync job appears to be querying older versions of the serverconfig object to get the ldap_config_id. If the older versions do not have a value set, the job will fail.
156347 - LDAP Sync job fail to remove a sub group when a sub group is deleted from AD.
157177 - LDAP Sync throws NullPointerException
157650 - com.documentum.fc.common.DfException constructor throws Exception:
java.lang.StringIndexOutOfBoundsException: String index out of range: 90
157759 - LDAP Sync throws Exception [DM_GROUP_E_UNABLE_TO_SAVE_EXISTING]error: "Cannot save group geoda-grp because a user already exists with the same name"; ERRORCODE: 100; NEXT: null
158197 - LDAP job fail to create the users cabinet though the argument create_default_cabinet set to true.
158766 - Running LDAP Sync throws the following LDAP NamingException:
javax.naming.NamingException: [LDAP: error code 1 - 000020EF: SvcErr:DSID-020513B8, problem 5012 (DIR_ERROR), data 8333]; remaining name 'CN=GAU2876SPE,OU=Security Groups,OU=Groups,OU=USPTO,DC=prepro,DC=local'"; ERRORCODE: 100; NEXT: null
153709 - Request for LDAPSynch job to have a switch to ignore case when comparing usernames
162830 - Ldap Sync job removes users default_group attribute
162684 - LDAPSynch leaves trailing spaces when setting user attributes with mapped custom values
164164 - LDAPSynch fails with DM_LDAP_SYNC_E_EXCEPTION_ERROR "String index out of range: 32" on getTruncatedString adding a member to a group if the username has trailing blank spaces that exceed the 32-character length limit.

Blame Everything on Testing

Your project is executing according to the schedule; the code development is done and unit tested, the Documentum applications have been installed and smoke tested; and UAT is about to begin. The designated tester on the team has been testing and writing scripts on the Test system. There’s a week allocated for testing the system in test. Oh, by the way, there’s a migration of legacy content being tested as well.

Yessss, I’ll be able to take my planned vacation
The testing is going excellent in Test. What do you think could go wrong? Well, first there are LDAP users in Prod and not in Test. Second, there are slight undocumented differences in the ACL’s between the two environments. Third, the migration will not be fully tested until it is run in the Prod environment. Fourth, UAT Users were not fully engaged during the testing and script writing phase of the project. Fifth, basic performance tests were run on Test, but real use tests to soak the system have not been executed. Sixth, a key developer is rolled off the project to start a new project at another company. Finally, seventh the sponsor of the project left the company and a new more technical sponsor is critiquing the application.

Can I get a refund for my vacation?
LDAP Users are in Production: The user that are imported will need to be added to groups if they aren’t from LDAP. The user logins will need to be tested. Renaming users will need to be tested.

ACLs: It is extremely tempting to make changes in Dev, QA and then Prod for ACLs manually without deploying them through a docapp or scripts each time. This inevitably causes slight differences between the environments.

Migration: When the migration is finally run in prod more focus will be on the results. The real users will be searching and finding bugs. Rerunning the migration a few times to prod should be built into the schedule.

UAT: No matter how much you tell the UAT testers that they need to be engaged and thinking about testing while reviewing the test scripts, they’ll find a ton of issues with the application during UAT. Showing them demos and prototypes during the development of the application helps, but they still won’t be able to really test until they sit down and seriously try to figure things out.

Performance: The Test environment was not tested for performance and there’s not enough money in the budget for a separate performance env. You’re left with trial by fire and it’ll be challenging.

Key Developer Rolls Off: This happens a lot. The Project Manager schedules a developer to be available for a few days after Unit testing. The best documentation of code and customizations could exist, but if the developer is no longer on the project, the learning is huge for someone else to fix bugs quickly during UAT.

New Sponsor: In this time of layoffs, you’ll get a number of sponsors who are reassigned of layed off. This means that the new person will come in with preconceived notions as to what needs to be done. This new person will want to make difference and a quick win is to delay the project while reviewing what it is suppose to do. What business problems are being solved, let’s look at the bigger picture here, why is this over budget, can we consolidate more, etc?

Stacation
The testing phase of projects will give you a few gray hairs. There are so many potential pot holes. How ever many days are scheduled for UAT, double it no matter what. If you want to go on vacation after, schedule it for next year.

Docapp Distractions

I know Composer is out there and useful in many installations, however it’s tempting to still use the Docapp Builder to build real time object models and once you start you kind of have to keep going. Also, there are still a ton of 5x installations out there that need to be maintained and eventually upgraded.

Different versions of Docapp Builder and Docapp Installer
I was recently in a situation where one developer was developing on D6 sp1 with a Docapp Installer version 6 and another was developing using 5.3 sp5 update1. The D6 developer was creating docapp archives for Forms and Process Builder which when installed using the 5.3 sp5 update1 installer left out certain form properties and functionality. It was a real waste of time trouble shooting these issues.

Creating a workflow docapp with auto activities for lifecycle promotion
If you create a workflow and have an auto activity for promoting a lifecycle state regardless of whether the lifecycle is added to the Docapp, the lifecycle will get added to the Docapp archive and installed on the target docbase.

ACLs with non dm_dbo domains
If you have set up ACLs with an owner that is not the dm_dbo (docbase user account) then these permission sets will not show up in the Docapp’s Lifecycle, Action, Add permission set drop down list.

Versions
If you are splitting the docapp work between a few developers, get ready to deal with a lot of versions of the docapp and all of the workflows, lifecycles, activities, etc.

ACL inheritance from Folder
If your docbase is set up with ACL inheritance from folders be sure to set the “System/Applications” folder ACLs. If you don’t do this, everytime you deploy a docapp its components, such as a lifecycle will inherit the ACLs of the docapp folder and may or may not work in the application.

Scoping of Display configurations
This is very strange when it happens. Let’s say you start out with a small object model of two levels and configure the display. Then you need to add a new parent level and redo the display. Sometimes the scope remains with the original model and object type. The only way I found to fix this was to dissect the database scope config and cut out the disease.

Mandatory attribute changes with old references
If you ever decide to change an object type’s attribute from required to not required, sometimes this change is held in a reference or cache somewhere. The only way I’ve been able to clear it is to delete the attribute using DAB, closing DAB, clearing the cache and inserting the attribute again.

Importance of having one source for docapp creation
I can’t stress it enough that Docapps should be created and control from one source, with the same versions of the Docapp Builder and Installer on the source and target machines. Configure the object type’s display only when the attributes and object model are final. Add workflows in with lifecycles. Try not to version docapps or its objects unless absolutely necessary. Finally, beware of the permissions that are inherited by the docapp installation.

Solution Demos: Catch 22

Damned if you demo, damned if you don’t, especially if your client is new to Documentum. You can talk about functionality, show the vanilla installation of Webtop, and still get surprised looks when you show the final solution. On the flip side, you can demo the solution when it’s not fully tested and have to dance around errors and incomplete development.

Demos of a client’s project are essential if the client reads the Functional Requirements Spec and the Tech Design without too many comments. This means they don’t understand and/or don’t have enough time to review it. This can be frustrating, but if you demo the solution in front of those same future users, you’ll get invaluable feedback and will eventually have a more successful launch of the solution.

Steps to successfully demonstrate your solution:

• Test the part of the solution that will be demo’d
• Plan talking around any part of the solution that is not completed
• Have an agenda of what will be shown during the demo
• Repeat to the clients/users that this is not a finished solution, that there will be bugs
• Try to have fun with your audience, this should not be too serious
• Have other technical resources there to take notes and comment on questions that pertain to their customizations
• Listen you your client’s comments and take their feedback seriously
• Make notes of comments that could form future opportunities, like “does this mean we have to sign on to another application each time we want to access it?”. This could mean that single sign on is in the future. Or, “I already fill out this information in the database, why do I need to do this twice?” This could mean an integration possibility to ease the transition to using Documentum, not to mention make finding content easier with more integrated attributes.
• Schedule a few demos to reduce the risk of disillusionment after an error causes one demo to fall short of expectations.
• Try to impress the client each time by showing something extra in the product that they might not have seen.
• Whatever you do, do not take screenshots and dummy up the solution. This will lead to more questions and anxiety over the progress of the overall solution.

From Functional Requirements to Tech Design

The most important part of designing a Documentum solution is to understand and translate the business and functional requirements into Documentum configurations and customizations. You have to create maps of all of the major components of requirements, matching each requirement to solution. You might use a traceability matrix or you might organize your specification similar to the functional requirements. It depends on the project scope and business expectations. My opinion is that if you need a traceability matrix the solution is too wide in scope or there are some trust issues with the business.

Document Types to Object Types

Scope of project phase
When reviewing the list of doc types in the functional specification do not take for granted that these are the final types of documents. A business analyst cares about capturing all of the possible documents, not necessary thinking about the scope of the project when he does so. Be sure to explicitly describe the scope of the project in your design. For example, the doc types may cover all content in the enterprise in order to create a comprehensive object model, however the scope of the current phase of the project may be a subset of those types. Do not over commit to the business what content will be covered in the first phase. When you demo the functionality, only show that phase’s content being imported and published. Try to reduce scope creep by repeating the project’s phase expectations and assuring that all content will eventually be brought into the system. This is a good opportunity to talk about a roadmap of the phases required to fully actualize the business’s total content management with Documentum.

Model review and rework
Roll up attributes as you work through each object type, finding commonalities across object types. Think about all the UI, TBO, ACL ramifications of your design. If the object model is huge, try to consolidate, look into using aspects as an alternative to many object types or many attributes.

Implementation design
Depending on the scope, you may be releasing the object types in phases. If this is the case, make sure the phase’s object types cover all of the document types, business processes and security requirements. You may want to prototype some of the object types and their relationships to importing and folder linking. For one-offs in a dev environment, Documentum Application Builder is the fast way to do this. For more methodical approaches, Composer is more portable and best practice going forward.

Metadata to Attributes

Match with OOTB attributes first
Don’t reinvent the wheel, search for a suitable existing attribute first then create a custom one. If there’s a requirement for a comments field, use the log_entry attribute. If there’s a status field, use the r_version_label.

Source of values

• Value assistance could be used for the easily maintained attribute values, which would be maintained using Doc App Builder or Composer. This uses docbasic.
• You could get a custom object to query for attribute values, which would be maintained by the business via the UI.
• You could query registered tables or views which could integrate with linked database tables
• You could read and parse a properties file maintained on the server.

UI constraints: repeating attribute, large text boxes
Think about how the users will react to the WDK repeating attribute dialog box. For large strings, you’ll have to put a text area in the forms.
Taxonomy to Folder Structure

Search ramifications
Giving context to search results is an important way to transfer knowledge. Repeating key attribute/value pairs (for searching) with folder hierarchy labels (for browsing) usually makes sense. If it doesn’t, maybe you are trying to put too much metadata on the object.

Simplify where ever possible
If you are going deeper than four levels, you better have a good reason. At a certain level there’s a “project” or “deal” or “product” level which repeats over time. This level should be closer to the top level, have some automated way to build new folders as new “projects” are added, and have an automated or easy way to archive, thus reducing the clutter of old content over time.

Business Process vs. share drive organization
Folder structure may be organized in many ways. A business process oriented structure may make more sense than strictly following the share drive approach of silos of data structured by business group. Avoid organizing content by date only. If there’s an end of quarter date use it, but don’t rely on it solely to find content.

Mix of common, evolved classification with more structured rules
Chances are good that you are moving from one established way of structuring content to another. Doing this right so the users know what they are doing in the new system without hours of training can be difficult, especially because the old way is usually not the best way. If the company is large, your headache is merging structures, if the company is small your headache is reorganizing silos of information. Sometimes both.

Modify according to folder/object type map
As the reality hits the road and you’re building folders and automating the linking of content to them, expect changes to the design, additions to the attributes needed, and delays to build and customize the right way.

Folder Structure mapping to Object Type plus Attributes

• Match Object Type and Attribute Key/Value pair Combinations to Folder paths
• Prototype the search and browse functionality
• Do subfolders follow the document templates?

Business Process to Workflow
This is where you’ll read the functional requirements of a process of getting content approved and have to figure out the specific activities involved for a workflow. Sometimes, Common business processes may not translate into a formal workflow. In this case, describe the steps of using the application and how the work can get done without a formal workflow. You’ll have to determine how to create decision point that splits the workflow if there’s a yes/no decision to be made. A common example of an auto-activity is the requirement to send a notification email with a link to the workflow’s package

Importing content
Check all assumptions involved with importing content into the system. It might be assumed that all content related to the first phase should somehow get into the system. The problem with this is that the contributors of the related content may not be ready to participate in the Documentum system. They may not be in the first phase.