In part two of this article: Using Alais Sets in Workflows and ACL Templates.

Introduction

Latin definition of alias: Otherwise, at another time.

Alias sets provide a means resolving attribute values that specify ACL, user and group names, and folder paths dynamically. This is an extremely
powerful feature of Documentum because it allows you to design ACLs, Lifecycles, and Workflows that can be used in multiple contexts without modification.

Common Uses

• Resolve a Sysobject’s owner name and/or ACL dynamically
• Resolve Workflow task performers dynamically
• Specify the Docbase location(s) for linking objects dynamically
• Take advantage of a rich scheme for resolving aliases in different circumstances

What is an Alias Set?

An alias set is simply a list of aliases (like “reviewer” or “supervisor”) and the values that they resolve to.
For instance, you might have an alias set that defines the following aliases and their values:
owner = "James Brown"
reviewer = "Legal Department"
approver = "Bob Dobson"
working_folder = "/Engineering/Offshore/Unreleased Files"
working_acl = "working_docs"
released_folder = "/Engineering/Offshore/Completed"
released_acl = "released_engineering_docs"
Note: In some circumstances you may assign an empty alias value and let the client application prompt the user for a value when it is needed.
Alias Sets are an important part of a complex Documentum system’s architecture,
providing a level of abstraction that can significantly reduce the effort needed to
administer the docbase. Alias sets remove the need to hard-code the names of users,
groups, locations, and permission sets throughout your application and instead provide
a means for setting these values dynamically as your personnel changes and your
business processes evolve.

High-Level Example

The benefits of Alias Sets can best be illustrated with an example. Imagine a company
with a simple review process for their documents: before a document is released, it must be
reviewed by the author’s manager. Using Alias Sets, each author can have his or her own
unique alias that relates the word “manager” to a user in the docbase. This allows a
single workflow to be used by every author in the docbase. The workflow is designed
to route the document to the “manager” alias, which will be resolved differently at
run time for each author. Instead of requiring a different workflow for each author,
a single workflow can be used with Alias Sets
Although this review process seems simple, without Alias Sets, it would be difficult to
implement since the manager’s name would have to be hard-coded as the reviewer, requiring
a different workflow for each author.

The dm_alias_set Object Type

Alias sets are stored as dm_alias_set objects in Documentum. It’s a fairly simple
object type with only eight attributes to worry about.
Five of the attributes are correlated repeating attributes meaning the value at a given index
position in one attribute is related to the values at that position in the other
attributes (similar to a two-dimensional array).
Single-valued Attributes:

object_name

The name of the alias set.

owner_name

The name of the user who owns the alias set.

object_description (optional)

A user-friendly description of the alias set.

Correlated Repeating Attributes:

alias_category (repeating)

The type of object or value that the alias at this position will resolve to. Valid values are:
0 – Unknown
1 – User (a dm_user user_name)
2 – Group (a dm_group group_name)
3 – User or Group
4 – Cabinet path (a dm_cabinet r_folder_path)
5 – Folder path (a dm_folder r_folder_path)
6 – ACL name (a dm_acl object_name)

alias_description (repeating)

A description of the alias at this position.

alias_name (repeating)

The name of the alias at this position.

alias_usr_category (repeating)

An alternate value for alias_category if you need one.

alias_value (repeating)

The value for the alias at this position.

An Example Alias Set

The picture below shows an example alias set viewed in Application Builder. The engineering_doc_aliases example is referenced throughout this article.

Referencing Aliases

To refer to an alias when setting an attribute value you prefix the alias name with a percent sign (example: %owner).
You can optionally specify the alias set name (example: %engineering_doc_aliases.owner). If the alias set name is not specified,
the system uses a rich set of rules to search for the alias name in various alias sets (see Alias Set Scopes)

Syntax for referencing aliases

%[alias set object_name.]alias_name
You can use aliases just like normal attribute values, and the server will resolve the alias to
the correct value. For example, this is an API command that uses an alias to set the acl_name on a document:
API>set,c,0900001880014d0b,acl_name
SET>%engineering_doc_aliases.working_acl
or you could just say...
API>set,c,0900001880014d0b,acl_name
SET>%working_acl
In the latter case the system will search the appropriate alias set ‘scopes’ until it finds the “working_acl” alias name.

Alias Set Scopes

Aliases are used to resolve a variable (the alias name) to a value. The value differs depending
on the context (different users have different alias sets with different values). This means that
the same alias name exists in multiple alias sets. For example, Bob might have an alias set with
%manager = Sally while Fred has an alias set with %manager = Jane. Since the same alias name
appears in multiple alias sets, the server needs a way to determine which alias set to apply
in each situation.
Of couse, you could fully qualify the alias name by specifying the alias set name (e.g. %bobs_alias_set.manager).
But if you only specify the alias name, the server will resolve the alias set by using a set of scoping rules.
The alias set that is used to resolve an alias in a given situation/location depends on the pecking order
of the scopes for the given location. For example, the resolution of an alias of the performer of a workflow task has a different algorithm than the resolution
of an alias of the folder path in a ‘link’ command. Making things a bit more complicated, the scopes themselves can have internal resolution algorithms.
The possible alias set scopes are described below.

• 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 (see the Using Alias Sets with Lifecycles section for syntax and explanation).Important: With a few exceptions, resolving aliases in the Lifecycle Scope requires that the sysobject is attached to a Lifecycle that
  has the alias set listed in its alias_set_ids repeating attribute. One exception is that ACL Templates can resolve Lifecycle scope aliases
  for sysobjects that are not attached to a Lifecycle.
• Workflow Scope – This is the alias set specified in a dm_process object’s perf_alias_set_id, also known as
  the workflow’s default alias set. A dm_process object is a template for workflow instances (dm_workflow objects).
  Aliases that specify performers of workflow tasks are resolved when a workflow instance is created. The default alias set’s id
  is copied into the dm_workflow object’s r_alias_set_id attribute when the workflow instance is created. The workflow-scope
  alias set can be specfifed on the “Template Properties” tab in Documentum Workflow Manager.
• 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>engineering_doc_aliases
• User Scope – 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 or 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.
• 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. You can
  set this attribute using the Server Configuration feature in Documentum Administrator or you can use DQL or the API.

Note: Search orders for scopes are described in subsequent sections that describe the places where aliases can be used.

Using the Resolvealias API command

You can use the resolvealias API command to ask the system to resolve an alias value.
It simply tells you what value the alias will resolve to based on the arguments you provide.
Resolvealias uses the same scope-searching rules that would be used during a save or link.
You can optionally include an alias set name. For example, you could ask the system what
value the alias %approver will resolve to for a given document…

Syntax for resolvealias

resolvealias,session,[object_id],%[alias_set_name.]alias_name
Example:
resolvealias,c,0900001880014ff3,%approver
Note: This command does not resolve and set any attributes defined as aliases to alias values.
Attributes are only resolved and set on save or link.

Creating and Inspecting Alias Sets

Both Documentum Administrator and Application Builder provide nice GUI interfaces for creating and maintaining alias sets.
However, if you need to create or inspect alias sets in a Docbase script or from a DQL command line
you can use the following syntax…

DQL to Create an Alias Set

CREATE dm_alias_set OBJECT SET object_name = ‘engineering_doc_aliases’

DQL to Append Aliases to the new Alias Set

UPDATE dm_alias_set OBJECTS APPEND alias_name = 'owner',
APPEND alias_value = 'James Brown',
APPEND alias_category = 1,
APPEND alias_usr_category = 1,
APPEND alias_description = 'Owner of engineering docs'
WHERE object_name = 'engineering_doc_aliases'
UPDATE dm_alias_set OBJECTS APPEND alias_name = 'working_acl',
APPEND alias_value = 'working_docs',
APPEND alias_category = 6,
APPEND alias_usr_category = 6,
APPEND alias_description = 'ACL for working docs'
WHERE object_name = 'engineering_doc_aliases'

DQL to Inspect the Aliases in an Alias Set

SELECT alias_name, alias_value, alias_category,
alias_usr_category, alias_description FROM dm_alias_set
WHERE object_name = 'engineering_doc_aliases
Important: The dm_alias_set object uses correlated repeating attributes. When using the DQL append statement to append aliases to an alias set,
you must provide values for all the repeating attributes to avoid getting an object index error on access (DM_API_E_BADATTRINDX).

Using Alias Sets with Sysobjects

Alias sets can be used to define the owner_name, acl_name, and acl_domain attributes for Sysobjects.
Aliases are resolved when the sysobject is saved. For example, you could create a dm_document and use the
aliases shown in the alias set in figure 1 to populate its owner_name and acl_name attributes…
object_name: My Document
r_object_type: dm_document
owner_name: %owner
acl_name: %working_acl
acl_domain: dm_dbo
Note: The “dm_dbo” alias used for the acl_domain is a special Documentum system alias that always
resolves to the docbase owner – which is also the acl_domain for System ACLs. You never have to
prefix the special alias “dm_dbo” with a percent sign
The next time the document above is saved, the system will try to resolve the owner name and ACL name to real values.
The system will search for the “%owner” and “%working_acl” aliases in the alias sets defined for the document’s various
alias set scopes. When resolving attribute values for sysobjects, the alias set scopes are searched in this order:

1. Lifecycle Scope
2. Session Scope
3. User Scope (first searches the user’s default alias set and then the user’s default group’s default alias set)
4. System Scope

If the aliases are not found in any of the above scopes, the system will return an Error on save and
reset the aliased attribute values back to the appropriate defaults

Using Alias Sets to Link Objects into Folders

Aliases can be used to specify folder paths when linking objects to locations in the Docbase.
The Link and Unlink API commands both accept aliases for the folder specification.

Syntax for link

link,session,object_id,folder_specification|alias

Using Alias Sets with Lifecycles

Aliases can be used in a lot of places in a Lifecycle definition. The advantage of using aliases rather
than hard-coded values in a Lifecycle definition is the ability to use the same lifecycle in multiple contexts and
even multiple Docbases. For instance the same lifecycle state transition might link one document into cabinet
A and another document into cabinet B because the documents have different alias sets. Or the same lifecycle
could be used in different docbases because its definition uses aliases where the Docbase environments
may differ. Alias values can be resolved when the lifecycle’s Docapp is installed (see Using Alias Sets in DocApps).
Here’s a list of where you can and can’t use aliases in a Lifecycle definition:
You can use an alias in:

• Add to Repeating Attribute action – for the attribute value
• Link to a New Location action – for the link location (folder path)
• Move all Links to Location action – for the unlink location (folder path)
• Remove from a Repeating Attribute action – for the attribute value
• Remove Link from Existing Location action – for the unlink location (folder path)
• Set Attribute action – for the attribute value
• Set Owner action – for the user
• Set Permission Set – for the ACL

You can’t use an alias in:

• Entry Criteria expressions
• Add Version Label action
• Remove Version Label action

A document’s lifecycle scope alias set is determined during lifecycle attachment and can be optionally
passed as a parameter to the lifecycle attach command. If you do this, the object ID of the alias set name (or index)
specified must be listed in the lifcycle’s alias_set_ids repeating attribute. Using the attach command, you can
refer to the alias set by name or by its index position in the lifecycle’s alias_set_ids repeating attribute. When using
aliases in lifecycle definitions, alias set scopes will be searched in the following order:

1. Lifecycle Scope
2. Session Scope
3. User Scope (first searches the user’s default alias set and then the user’s default group’s default alias set)
4. System Scope

Syntax for Lifecycle attachment:

attach,session,object_id[,default|policy_id[,position|state_name]][,alias_set_position|alias_set_name]
Example:
API>attach,c,0900001880014ff3,default,engineering_doc_aliases
The alias set ID at index 0 of the dm_policy object’s alias_sets_ids attribute is considered the lifecycle’s default alias set.
The default alias set will be set as an objects lifecycle scope alias set during lifecycle attachment if no alias set is explicitly
specified in the attach command.
To see a list of the alias set names that are associated with a lifecycle you can ask for the _alias_sets
computed attribute (rather than having to de-reference IDs listed in alias_set_ids)…
API>get,c,<object_id of dm_policy>,_alias_sets
result> engineering_doc_aliases
offshore_aliases
corporate_aliases

Three important notes regarding Lifecycles and alias sets:

1. You need at least write permission on the lifecycle (dm_policy object) to append alias sets to it.
2. You can’t modify an alias set that is listed in the r_alias_sets attribute of an _installed_ lifecycle. You have to uninstall the lifecycle first.
3. The Application Builder interface for appending values to a Lifecycle’s alias_set_id’s
   attribute is on the “Default Alias Set” dialog in the section labeled “Additional Alias Sets”.

Tips for Using Alias Sets

A trick for quickly getting the alias set name for any alias set scope where the alias set is stored as an r_object_id (Lifecycle, User, System)
is to ask for the calculated “_alias_set” attribute. For example to determine the lifecycle scope alias set name for a dm_document you can save
the step of de-referencing the id stored in the document’s r_alias_set_id attribute by asking for the _alias_set attribute as shown in the
example below:
API>get,c,0900001880014ff3,alias_set
result> engineering_doc_aliases