Using Alias Sets Part 2

Introduction

This is Part 2 of the Using Alias Sets article posted in July 2004. The first article covers the basics of alias sets and how to use them in lifecycles. This article continues on the topic by covering the use of alias sets in ACL templates and Workflows, two of the most powerful uses of alias sets.

Quick Review of Alias Sets

Part 1 of this article has a full description of the alias set object type and an explanation of alias set scopes and alias resolution algorithms. The general concept of alias sets is that they are lists of alias names and the values that they resolve to. The values can be users, groups, ACLs or folder paths and they can be used in several places in lifecycle definitions, like the folder path when linking sysobjects, as activity performers in workflows, and as accessors in ACLs.

Consider the following two alias sets, Offshore Operations Contracting and Ground Operations Contracting, both shown open in Documentum Application builder below. They both contain the same set of alias names, but the alias values are different except for “Legal Reviewers”. We will refer to these example alias sets in the examples that follow.

Using Alias Sets in ACL Templates

What is an ACL Template?

An ACL template, also known as a Permission Set Template, is a special type of ACL where the accessors are alias names. When you assign an ACL template to the acl_name of a sysobject and save the sysobject, the system creates a copy of the template (an instance) and tries to resolve all of the aliased accessors. The fully resolved instance actually gets assigned to the sysobject, not the template. Subsequently, if any of the permissions on the ACL template change, ACL instances that reference that template will be updated by the system to reflect the changes.

Advantages of Using ACL Templates

There are several advantages to using ACL templates over regular ACLs. For one, it can save you from having to create lots of distinct ACLs if you need accessors that are specific to individual objects. Having accessors set to aliases also allows the ACL to be flexible enough to work in multiple contexts and repositories. For instance you could have a “department manager” alias for an accessor in an ACL. Maybe the manager should always have “Delete” permission on documents. You could use the same ACL for documents in different departments or repositories with different managers because the “department manager” alias can resolve to the correct manager.

Relevant Object Types and Attributes

An ACL template, like a regular ACL is of the object type dm_acl, however its acl_class attribute is set to “1″ which means “Template ACL”. Resolved instances of an ACL template are also of the type dm_acl, but with an acl_class of “2″ meaning “Template Instance”.

These are the possible values for the dm_acl object’s acl_class attribute:

• 0 - Regular ACL
• 1 - Template ACL
• 2 - Template Instance
• 3 - Public ACL

Note: See Part 1 of this article for a full review of the dm_alias_set object type and its attributes.

Example ACL Template Shown in Administrator

Notice that in the ACL template in Figure 3 below, all accessors except for dm_world and dm_owner are specified as aliases (as denoted by the ‘%’ prefix). Dm_world and dm_owner are special system aliases that don’t require the ‘%’ prefix.

Alias Resolution Scopes for ACL Templates

When the system needs to resolve aliases in an ACL template in order to create a template instance, it searches for the aliases values in several places (scopes) in a predefined order.

Important: During ACL resolution, the system will only continue searching at the next scope if the alias set for the current scope is undefined, otherwise it returns an error.

For ACL template resolution alias set scopes are searched in the following order:

1. Lifecycle Scope - This is the alias set specified in the r_alias_set_id attribute of a sysobject. This lifecycle scope alias set is normally assigned to a sysobject during lifecycle attachment.
2. Session Scope - This is the alias set specified in the alias_set attribute of the session config object (sessionconfig). Sessionconfig is a special non-persistent object that has the lifetime of a Docbase session. Its attributes are accessible using the API’s Get and Set commands. Interestingly, this alias set scope must be specified using the object name of the alias set, not the object id which is used in all other scopes. You can set the Sessionconfig’s alias_set attribute using the following API syntax:

API>set,c,sessionconfig,alias_set
SET>Offshore Operations Contracting

3. User Scope
1. User’s Alias Set - Also known as the “user-level default alias set”, this can be the alias set specified in the alias_set_id attribute of a dm_user object
2. User’s Default Group’s Alias Set - The alias_set_id attribute of the user’s default group.
You can set these attributes using the User and Group Management features in Documentum Administrator or you can use DQL or the API.
4. System Scope - Also known as the “system-level default alias set”, this is the alias set specified in the alias_set attribute of the server config object (serverconfig). Serverconfig is a sysobject of the type dm_server_config.

Note: If the system is unable to resolve any alias in the ACL template from the first non-null alias set it finds in the order shown above, it will return the following error:

The dm_45xxxxxxxxxxxxxx_xxxxxxxx ACL

When the system resolves an ACL template to create a real ACL (an ACL template instance), it names the new ACL using a naming convention that starts with “dm_” followed by a 16-digit hexadecimal number, followed by an underscore and another 8-digit number. The 16-digit number is the r_object_id of the ACL template that this ACL instance was created from. The last eight digits are a unique identifier for the ACL instance.

Example: 451098b180000d02_80000d4d

One disadvantage of using ACL templates is that the “dm_45″ ACL name is not as user-friendly as a normally named regular ACL when displayed on a properties page, etc. For example, it’s not as easy for an administrator to verify an ACL on an object just by looking at the ACL name. This problem is usually outweighed by the benefits of using ACL templates.

An Example ACL Template Scenario

Consider an example scenario where a company is managing contracts in a repository for two divisions of the company: Offshore Operations, and Ground Operations.

The managed contract documents for both divisions should have similar security models but with different accessors and need to be routed on similar approval workflows but with different participants. A standard contracting security model and workflow template(s) can be realized by using ACL and Workflow templates that reference alias sets.

The Ground Operations Contracting Alias Set has the following aliases defined:

Also in this example there exists a single Contracting Lifecycle to which is applied to all contracting documents. Contracting Lifecycle has three states: Draft -> Approved -> Executed.

Important: Alias sets used at the lifecycle scope must be listed in the lifecycle’s list of acceptable alias sets (alias_set_ids repeating attribute).

When the lifecycle is applied to a contracting document, an alias set is specified based on the department for which the document is created. For example when using the API, the alias set can be specified as the last parameter to the lifecycle attachment command, attach:

API>attach,c,0900001880014ff3,Offshore Operations Contracting

Imagine that two contracting documents are created, one in the Ground Operations department, and one in the Offshore Operations department. The Contracting lifecycle is applied to each document so that each is given the appropriate alias set for its department. Then when the Contract Development ACl template is applied to each document an appropriate ACL for each document’s department is created and applied.

In this example each department has its own contracting alias set. Offshore Operations and Ground Operations have the alias sets Offshore Operations Contracting and Ground Operations Contracting respectively (also shown in Figure 1 and Figure 2 above in the article)

The Offshore Operations Contracting Alias Set has the following aliases defined:

The Contract Development ACL Template has the following permissions defined (also shown in Figure 3):

When applied to the Offshore Operations document, the Contract Development ACL Template creates the following ACL instance based on the documents’ lifecycle-scope alias set, Offshore Operations Contracting:

451098b180000d02_80000d4d

When applied to the Ground Operations document, the Contract Development ACL Template creates the following ACL instance based on the documents’ lifecycle-scope alias set, Ground Operations Contracting:

451098b180000d02_80000d4e

Using Alias Sets in Workflows

Aliases can be used to define the performer name in workflow activities. This allows the activity performers to be resolved either manually by a workflow participant or supervisor or dynamically based on the available alias sets. This gives flexibility to the workflow and makes it easier to use the same workflow in different situations or repositories.

Specifying an Alias as a Workflow Participant

When you create a workflow using DCTM Workflow manager, you can designate the performer of an activity to be an alias that will be resolved manually by a user or automatically by the system. There are two opportunities to allow users to specify alias values manually:

1. On the Start of the Workflow - If a workflow is initiated with a default alias set that has any alias names listed without values then the client application should prompt the Workflow Initiator for the missing alias values. The activity should be set to resolve the performer alias from the “Default Alias Set” (see the first radio button in Figure 4).
   

   Note: If a custom client application is initiating the workflow, it must implement the facility to do this.

2. During the Performance of a Previous Activity - This can be accomplished by specifying that the performer of a specific (previous) activity select the performer of this activity (see the middle radio button in Figure 4) using Workflow Manager.

On the other hand, when resolving performer alias values automatically, you can request that the system resolve the alias from one of the four following alias set scopes:

1. Default Alias Set - This is the workflow template’s default alias set. On the workflow template object this is dm_process.perf_alias_set_id. On the workflow instance, this is the dm_workflow.r_alias_set_id attribute.
2. Specific Alias Set - This can be any alias set that you select from the repository.
3. Alias Set of Document in Package - This is the alias set of the package being routed in the workflow.
4. Alias Set of Previous Performer - This is the alias set of the user who completed the previous activity.

   Note: If the previous activity was an automatic activity, the previous performer may be the docbase owner or a system user. Sometimes it is useful to create a dummy activity with a dm_noop method specifically to set the performer of the previous activity.

The dialogs from Workflow Manager shown below illustrate the selection of an activity’s performer as an alias and specification of the alias set from which to resolve the performer.

Alias Resolution Algorithms for Workflow Participants

The algorithm used to resolve participant aliases depends on the choice you select for the source of the alias set (Figure 5). This setting is stored in the dm_activity object’s resolve_type attribute as an integer. These are the possible values for dm_activity.resolve_type:

• 0 - Default
• 1 - Package
• 2 - User

If you choose “Specific alias set” then the server will only search that alias set for alias values. However, if you choose one of the other three options, the server uses a pre-defined algorithm to find the alias name and value.

• Default Resolution Algorithm - This algorithm is used when the activity’s resolve_type attribute is set to 0:
1. Searches the default alias set specified for the workflow (if there is one).
2. Searches the alias set defined for the current session.
3. Searches the user alias set for the previous performer
4. Searches the default group alias set for the previous performer
5. Searches the alias set specified for the Server configuration.
• Package Resolution Algorithm - This algorithm is used when the activity’s resolve_type attribute is set to 1:
1. If the activity object’s resolve_pkg_name attribute is set, then searches the alias set of the named package.
2. If the activity object’s resolve_pkg_name attribute is NOT set or the alias was not found in the named package, then the server searches the alias set of each item in the first package in the order that the items were added to the package.
3. c. If the alias was not found in the first package searches, then searches the alias sets of the objects in the next package that was added to the activity and so on until the alias is found or all objects in all packages are searched.
• User Resolution Algorithm - This algorithm is used when the activity’s resolve_type attribute is set to 2:
1. Searches the alias set of the user object of the previous activity’s performer.
2. Searches the alias set of the previous performer’s default group

FAQ

Can I have a mix of real users and aliases as accessors in my ACL template?

No, you can’t. All accessor names are converted to alias names when an ACL template is saved.

How do I go about deleting unwanted alias sets and objects that reference them?

If possible, first delete any ACL or Workflow templates or instances that reference the alias set. Then delete the alias set. Then run the dm_clean job. Dm_Clean should destroy any ACL instances orphaned by the deletion of the alias set.