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.

Figure 1:
Alias Set for Offshore Operations Contracting shown in Developer Studio

Figure 2:
Alias Set for Ground Operations Contracting shown in Developer Studio

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.

Figure 3:
ACL Template for Contract Development shown in Administrator

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

1. 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.

1. 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:

DM_ACL_E_CANT_CREATE_INSTANCE

Severity: ERROR
Message Text: Cannot create an instance %s of template ACL %s based on alias set %s.
Cause: Failed to create an instance of the said template ACL. There must exist at least one alias which can’t be resolved based on the said alias set.
Action: Change the associated document instead so that a new internal ACL will be created.

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:

Contract Rep (user) – James Brown

Contract Supervisor (user) – Bob Dobson

Gate Keeper (user) – Jenny Smith

Contract staff (group) – ground ops contracting

Legal Reviewers (group) – legal department

Signatories (group) – ground ops signatories

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:

Contract Rep (user) – George Duke

Contract Supervisor (user) – Mark Babbins

Gate Keeper (user) – Hal Thompson

Contract staff (group) – offshore ops contracting

Legal Reviewers (group) – legal department

Signatories (group) – offshore ops signatories

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

%Contract Rep – Delete
%Contract Staff – Version%Contract Supervisor – Write%Gate Keeper – Read

%Legal Reviewers – Read

%Signatories – Version

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

George Duke – Delete (%Contract Rep)

offshore ops contracting – Version (%Contract Staff)

Mark Babbins – Write (%Contract Supervisor)

Hal Thompson – Read (%Gate Keeper)

legal department – Read (%Legal Reviewers)

offshore ops signatories – Version (%Signatories)

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

James Brown – Delete (%Contract Rep)

ground ops contracting – Version (%Contract Staff)

Bob Dobson – Write (%Contract Supervisor)

Jenny smith – Read (%Gate Keeper)

legal department – Read (%Legal Reviewers)

ground ops signatories – Version (%Signatories)

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.

Figure 4:
Defining an Alias as a Workflow Activity Performer (Click to Enlarge) 

Figure 5:
Defining an Alias Set for the Activity Performer (Click to Enlarge)

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.