Overview

The Documentum Content Server includes facilities for sending automatically generated emails to
administrators and end users. This article explores the mechanisms behind these facilities and
how they can be configured and customized to meet the needs of your organization. Please note
that the scripts, executables, and method names mentioned in this article are applicable to
Windows-based Content Servers only. The general concepts do apply to Unix-based systems,
but there will be differences in file names, locations, and attribute values.

Technology Primer

Before moving on with discussions of the Documentum email facilities, it is important to understand
a few of the concepts and technologies in use when sending and receiving email in general.

SMTP – SMTP stands for Simple Mail Transfer Protocol. This is a widely-used
internet protocol (TCP/IP) for communicating with mail servers. You may have noticed that
the Documentum Content Server installation application asks you for the name of an SMTP
server during installation. This is because, by default, Documentum uses SMTP to send email notifications.

MAPI – MAPI stands for Messaging Application Programming Interface. It is a
Microsoft-specific mail API that is part of the Windows operating system. It allows applications
to generate and send email messages and peform other email related tasks within MS Exchange and
Outlook. Documentum has recently (starting with version 5.1) dropped support for MAPI due to
newly added security “features” in MAPI that require user interaction to send emails.

POP – POP stands for Post Office Protocol. It is a widely-used internet protocol
(TCP/IP) that mail clients use to recieve email from mail servers. POP3 is the
current incarnation of the Post Office Protocol.

IMAP – IMAP stands for Internet Message Access Protocol. IMAP is an alternative
to POP for recieving email messgaes from and email server. IMAP4 is the latest version of IMAP.

Email Notifications from the Content Server

Standard Email Sources

The Documentum Content Server sends emails that originate from the server itself, like administrative
notifications for low disk space, etc. It also sends emails triggered by Documentum applications
such as task notifications from DCM or Web Publisher Workflows. Most Documentum email notifications
are triggered by events in the repository and correspond to tasks and messages that get queued
to a user’s Documentum Inbox. All out-of-the-box Documentum email notifications
originate from one of three sources:

• Jobs
• Registered Events
• Workflow Tasks

Email Methods

All repositories install pre-configured with two methods (dm_method objects) that are designed to
sending emails, “dm_event_sender” and “mail”.

dm_event_sender – This method is called when registered events are raised in the
repository and when objects are queued to Inboxes. This method sends emails by calling the Dmbasic.exe
executable and passing it the name of an external Docbasic method to run (by default, dm_event_sender.ebs).
The external Docbasic method then constructs the email message in a temporary file and calls an
executable like smail.exe to send it. On Windows platforms, the name of the executable is hard-coded
in the Docbasic method.

mail – This method is used for sending non-event-related and ad-hoc email notifications. It
gets the name of an executable for sending emails from its method_verb attribute and takes a subject line, the name of the
email recipient, and the name of a temporary file containing the message as arguments.

Email Executables

Smail.exe and Mail.exe – On Windows platforms, the Documentum Content Server (5.1 and higher) by default uses
two different mail executables, named smail.exe and mail.exe. Smail.exe is used for event notifications that
are handled by the dm_event_sender method. Mail.exe is the default setting for the method_verb attribute of the mail method
which is used for non-event notifications and ad-hoc emails.
Both of these SMTP-supporting executables install automatically
with the Content Server software. They are why you don’t have to install a separate
email application on the Content Server machine. You will however be prompted during
the installation process for the name of an SMTP server for the mail executables to send email
through. When you reach this step you should provide the name of your organization’s
SMTP server.

Note: Microsoft Exchange can be configured,
in some versions via an add-on connector, to support the SMTP protocol.

Msmail.exe – Older versions of the Content Server (pre 5.1) use the MAPI email by default.
This older configuration utilized an Outlook client that had to be installed on the
Content Server machine for sending emails. A version of the MAPI-enabled executable, msmail.exe,
still ships with newer versions of the Content Server, including 5.3, and can be found in Documentumproduct<server_version>bin,
This executable can be used with MAPI-supporting email servers like Lotus Notes.

Figure 1:
Email Control Flow

SMTP Account for Sending Emails

In order for email notifications to work properly, the Content Server’s installation owner
(commonly “dmadmin”) should have a user account with the SMTP server. This is the account
specified in the user_address attribute of the dm_user object that has the same user_name
as the OS account that installed the Documentum server software.

The installation owner’s
account will appear in the “From” field of emails sent from the Content Server. In other
words, Documentum email notifications will appear to have been sent from the installation
owner. Note that (unfortunately) smail.exe does not currently allow for authentication
with secured SMTP servers.

Documentum’s Email-related Object Types and Attributes

Support for email is build into Documentum’s base object model. Below is a list of Documentum base
object types and their email-related attributes.

• dm_user.user_address – The dm_user object type has an attribute called “user_address”
  that is optionally populated with an email address of the user. Note that Administrator forces you to
  enter a value for this attribute but it is not actually mandatory. A common practice for disabling
  email notifications to a given user is to set that user’s user_address to ”, the empty string
  (see Tips and Troubleshooting for a DQL example).
• dm_group.user_address – The dm_group object type has an attribute called “user_address”
  that is optionally populated with an email address for the group or that of a representative user for the group.
• dm_job.method_arguments – Jobs are chron jobs that are run by the Content Server.
  Jobs may send email on completion or if they generate an error or warning during execution.
  The -queueperson argument which is (optionally) provided in the method_arguments attribute
  of a dm_job specifies the repository user who should receive notifications generated for
  the job (via both Inbox and email). If the -queueperson argument is not specified, the server
  falls back to the user specified in the operator_name attribute of the the dm_server_config object.
• dm_server_config.mail_method – This attribute on dm_server_config tells the Content
  Server which method to use for sending email. Valid values are “dm_event_sender” (the documented default for Windows platforms),
  “dm_event_sender_template” and ” (empty string – the actual default). The values “dm_event_sender” and empty string will
  both cause the server to use dm_event_sender.
• dm_server_config.smtp_server – This attribute on dm_server_config specifes
  the name of an SMTP server that the Content Server will use to send emails through. This value
  is only used on Windows-based systems.
• dm_server_config.operator_name – Among its other uses, this attribute which is
  the name of a repository user, specifies who will recieve notifications from jobs and methods that
  are not provided with a -queueperson argument. This attribute is pre-populated when the repository
  is created with the name of the owner of the dm_system_config object (the docbase owner,
  not the installation owner).
• dm_server_config.web_server_loc – This attribute is used to build the server portion of
  URLs in dm_html_sender and dm_wp_sender.
• dm_server_config.web_server_port – This attribute is used to build the port number portion of
  URLs in dm_html_sender and dm_wp_sender.
• dm_server_config.rightsite_image – This attribute is used to build the application portion of
  URLs in dm_html_sender and dm_wp_sender.
• dm_email_message – The dm_email_message object type is an out-of-the box
  object type provided by Documentum for storing archived emails. This object type has nothing
  to do with the Content Server’s email notification functionalities.

Changing the Mail Executable

If you want to change the executable that the Content Server uses to send non-event and ad-hoc email notifications, you can update
the “mail” method’s method_verb attribute to the following string:

<path_and_file_name_of_new_mail_executable> <arguments>

Note:
The executable’s path can be absolute or relative to $DOCUMENTUM_HOME$bin

Here is an example DQL query to perform the update:

UPDATE dm_method OBJECTS SET method_verb = ".msmail.exe" WHERE object_name = 'mail'

In order to change the mail executable used by the dm_event_sender method for event notification emails, you’ll need to
change the hard-coded executable name in dm_event_sender.ebs (or dm_html_sender.ebs or dm_wp_sender.ebs depending on which method you are using).
See Customizing Mail Messages for instructions
on changing the mail executable used by dm_event_sender.ebs.

Changing Email Configurations in dm_server_config

Changing the SMTP Server

If after installation you need to change the name of the SMTP server that the Content
Server uses, you can modify the smtp_server attribute of the repository’s dm_server_config object.
Here is an example of using a DQL query to perform the update (this setting can also be
configured through Documentum Administrator):

UPDATE dm_server_config OBJECTS set smtp_server = '<new_smtp_server_name>'

Changing the Mail Method

The attribute on dm_server_config called “mail_method” controls which server-side method is used to send event-related emails.
By default the mail_method attribute is set to a value of “dm_event_sender” (or by my observations, empty string) which is the
name of a dm_method that exists in all Documentum repositories. Currently the only
other valid values for the mail_method attribute are “dm_event_sender_template” and
empty string. The empty string value appears to have the same affect as specifying “dm_event_sender”.
The value “dm_event_sender_template” is for use when Documentum Business
Process Designer is installed and you are planning to use templated mail message feature
with workflows (a configuration not covered in this article).

Here is an example DQL query to change the mail method (this setting can also be configured through Documentum Administrator):

UPDATE dm_server_config OBJECTS set mail_method = ‘<new_mail_method_name>’

Changing Email Configurations in Server.ini

Disable/Enable Email Notifications Globally

To globally enable or disable email notifications from the Content Server, you can modify the
mail_notification entry in the Content Server’s server.ini file, located in the server’s config directory.
Valid values for this key are “T” and “F”. The default value is “T” and enables the sending of email notifications.

Configuring Group Email Behavior

Starting in version 5.3, the Content Server’s server.ini file also has a key called “use_group_address”.
The use_group_address key specifies who will receive an email message when a notification is sent to
a dm_group. These are the valid values and their meanings (the default value is 0):

0 – Every dm_user listed in the dm_group’s (computed) i_all_users_names attribute
will receive an email. This includes all users that are members of groups that are members of the group and so on.

1 – A single email will be sent to the address specifed in the dm_group object’s
group_address attribute. Note that if the group_address attribute is empty then the server
falls back to option 0.

2 – This value cause emails to the be sent to both the group address and all users in the group.

Registering Events and Queueing Objects

Registering Events

Documentum email messages can be triggered by events that occur in the repository. Some events
cause an email notification to be sent by default, while others must be configured to trigger a
notification. You can configure events to trigger notifications by using the “register” API method.
The “register” API method causes an event to send a notification to the user who registered it.
Any user can register to recieve notice of an event on a single object, but only superusers
can register for events on all objects of a specified object type. The syntax of the
“register” API method is shown below:

dmAPISet("register,<session_id or use 'c'>,<r_object_id of single object or r_object_type>,
<event_name>[,priority][,send_mail]","<text of message>")

The optional send_mail parameter of the “register” API command specifies if an email is sent
in addition to a notification to the user’s inbox. The default value is “T”. As an example,
the following API command will cause an email notification to be sent to the current user when
a document with the shown r_object_id is checked out:

dmAPISet(“register,c,0976827008721234,dm_checkout”,

“This important object has been checked out!”)

For a full list of registerable events (like dm_checkout), see Appendix B of the Content Server API Reference
for your version of the server (use these events for the <event_name> parameter). Below is a list of event names
that that will be handled by the out-of-the-box dm_event_sender.ebs and dm_html_sender.ebs docbasic methods.
Other events not in this list can be registered, but you’ll probably want to add custom handler cases for
them in the “construct_required_email_parts” subroutine of the sender method your system is using.
Otherwise the events will be handled (sometimes akwardly) by the catch-all “else” case in the
subroutine (see Customizing Mail Messages).

//General repository events:

dm_checkin
dm_checkout
dm_destroy
dm_fetch
dm_lock
dm_unlock
dm_branch
dm_prune
dm_mark
dm_save
dm_status
dm_link
dm_unlink
dm_archive
dm_archive_done
dm_restore
dm_restore_done

//Special events:

Job_Failure
Agent_Exec_Failure

//Old-school EDMS98 router events:

dm_end
dm_halt

//Workflow and router events:

dm_acquire
dm_force
dm_forward
dm_reassign
dm_route
dm_signoff
dm_start
dm_reverse
dm_pause
dm_resume
dm_startedworkitem
dm_selectedworkitem
dm_completedworkitem
dm_reassignedworkitem
dm_delegatedworkitem
dm_createworkflow
dm_startworkflow
dm_terminateworkflow
dm_abortworkflow
dm_changestateworkflow
dm_abortactivity
dm_autotransactivity
dm_changestateactivity
dm_changestateproces

Note: If you get tired of recieving email messages for a given event you can use the
“unregister” API method to remove the registration a notification. See the API reference for syntax.

Queueing Objects

If you have an object to place in a user’s inbox queue, you can raise custom events (with custom names)
yourself programatically by using the “queue” API command. The decision to raise custom events that
trigger email notifications may justify a modification to the mail sender method to handle the new
event name (see Customizing Mail Messages). The syntax of the queue command is shown below:

dmAPIGet("queue,<session_id or use 'c'>,<r_object_id of object to place in queue>,
<user_name of user to recieve the notification>,<event_name or custom event_name>,
<priority>[,send_mail],[due_date],<message to user>")

When queueing workflow tasks, the syntax is slightly different:

dmAPIGet("queue,<session_id or use 'c'>,workflow_id|workitem_id,[recipient],
event_type,[priority],[send_mail],[due_date],[message]")

Objects can be removed from the queue by using the “dequeue” API method. See the API reference
for syntax. Note that auditing an event (via the Audit API) does not automatically generate an email notification.

The Event Sender Docbasic Methods

The Content Server ships with several Docbasic methods that generate email messages. These methods are
located in Documentum’s installation home directory under Documentumproduct<server_version>bin.
For Content Server 5.3 these are the methods provided:

• dm_event_sender.ebs (default – sends emails in text format)
• dm_html_sender.ebs (sends emails in html format)

For Web Publisher workflow task notifications the methods is the following:

• dm_wp_sender.ebs

Available from Documentum Support for DCM-enabled systems:

• dm_dcm_event_sender.ebs

Docbasic methods are plaintext files that you can modify (after saving a backup of the original,
of course). The file extension for Docbasic files is “.ebs”. See the Documentum Docbasic Language
Reference for more information about the Docbasic language. By default the Content Server uses
dm_event_sender.ebs to construct and send emails.

Note: The dm_event_sender method object in the repository should not be confused with the
dm_event_sender.ebs Docbasic method. These are two distinct, but related, concepts.
The dm_event_sender method object’s method_verb attribute may point to the dm_event_sender.ebs
Docbasic method which lives outside of the repository on the Content Server’s file system.
Alternately, the dm_event_sender method object may be configured to point to some other
program or Docbasic method on the file system, such as dm_html_sender.ebs.

Changing the Event Sender Docbasic Method

If you want to change the sender method used by the Content Server you can update the
dm_event_sender method object’s method_verb attribute. For example, organizations often
want to change the server to use the dm_html_sender.ebs method that sends prettier
html-formatted emails. The method_verb attribute has a string value in this format:

.dmbasic.exe -f.<new_mail_method_to_use> -eMail

Here is a DQL example to change the email method (note that this can also
be done through method administration in DCTM Administrator):

UPDATE dm_method OBJECTS SET method_verb = ".dmbasic.exe -f.dm_html_sender.ebs -eMail"
WHERE object_name = 'dm_event_sender'

Customizing Mail Messages

Many organizations want to customize the content of the email notifications sent by the
Content Server. This can be done without much trouble by modifying the docbasic sender
method that your system is configured to use (dm_event_sender.ebs, dm_htm_sender.ebs, etc.).
The examples below show how to modify dm_event_sender.ebs, but the concepts are the same
for dm_html_sender.ebs and dm_wp_sender.ebs. When you open your sender method in a text
editor you will find that it is significantly predisposed for modification. For example
you’ll see comment lines like, “dm_event_sender.ebs and dm_html_sender.ebs are interchangeable;
make sure that changes are reflected in both files.” – which, incedentally, is good advice.

It is helpful to know that the dm_event_sender.ebs script is one of Documentum’s oldest artifacts.
Many of its concepts and email sections date back to EDMS98 (routers and “3.1 computer-readable data” for example).
The emails that it generates out-of-the-box are, well, cryptic at best. It’s no surprise that many organizations
find a need to customize it.

The entry point of the sender methods is a subroutine called “Mail”. The Mail subroutine first does a
lot of validation of the arguments passed in to the method and then calls a subroutine to construct the
content of the email message. Take a look at the thirty one parameters passed into the Mail subroutine.
These are what you have to work with without making a connection back to the repository to ask for
more information. The name of the subroutine that contructs the email content is “construct_required_email_parts”
and this is where customizations are commonly made.

Customizing the construct_required_email_parts Subroutine

The “construct_required_email_parts” subroutine first adds a header to the message that displays
which docbase the notification was sent from.

Print #2, “In docbase “”” & docbase_name & “””:”
Print #2, “”

You can change the text of this header or comment it out if you like (Docbasic comments begin with a single quote).

Next, the subroutine enters a gigantic “Select Case” statement that keys on the event_name parameter
passed into the method. Each event case is handled similarly. First the object_info_flag, task_event_flag,
and router_event_flag are set to the appropriate values for the event. These variables are passed-by-reference
to various downstream subroutines and used to determine which additional sections to append to the email content.

object_info_flag – If set to “true” will cause aditional attribute information about a
queued object to be added to the email content (by default just the object name).

task_event_flag – Is used for workflow task events and causes task-related information
to be added to the email content (like the task name and priority).

router_event_flag – Is used for workflow task events and old-school router events and
causes information about those to be added to the email (like workflow or router name and supervisor).

Then an event-specific subject line and event notification sentence are constructed based on the available
parameters passed into the subroutine. Change the text of these strings if you like, but remember that
the resulting subject line must begin and end with double quotes because it gets passed as a separate
parameter to the mail executable’s command line.

At the very end of the gigantic case statement is a catch-all “else” section labeled “User-defined events”.
This is where any unrecognized event is handled. Just above this else statement is where you can add
additional cases to handle any custom events that you want to raise. For example:

Case “my_custom_event”
object_info_flag = “true”
task_event_flag = “false”
router_event_flag = “false”
subject_line = “Look at me! I handled a custom event called, ” & _
CleanQuote(event_name) & “, in repository ” & CleanQuote(docbase_name)
Print #2, “You should know about this stuff: “”” & message_text & “””.”

Removing the “3.1 computer-readable info” Section

If you’d like to remove the akward “3.1 computer-readable info” section that gets appended to email
notifications (and tends to alarm users), find the following “If” statement and change “true” to “false”.

if true then
call append_3point1_data (_

Changing the Mail Executable

To change the executable used by dm_event_sender.ebs, you need to find the actual line of code
that calls the executable and change it there (shown below).

If platform$ = “WIN32” Then
mailScript$ = “.smail.exe”

…could be changed to:

If platform$ = “WIN32” Then
mailScript$ = “.my_mail_program.exe”

Note: Depending on the command line arguments that the new mail executable takes, you may need to change the parameters that are sent to is as well.”

Getting Unavailable Information

Finally, if the thirty one parameters passed into the Mail method are not enough information to
generate the email messages that you require, see if you can pass in the additional information
in the method’s -message_text argument. Otherwise, as a last resort you can connect back to the
repository and query for the information you need. I won’t give an example here because it evokes
visions of Rube Goldberg machines and is likely a bad idea in general (for server performance and
stability reasons) – but it is possible. See your Docbasic reference for more information about
connecting to the repository. 😉

Tips and Troubleshooting

Question:
How can I quickly test that connectivity between my Content Server
and SMTP server is working?

Answer:You can run smail.exe manually from a command line by opening a console
window to Documentumproduct<version>bin and typing the command shown below. First type a short message into a temporary text file for use as the mail body. This should cause an email to be sent to your email account via your SMTP server.

smail.exe -u <installation owner> -p <installation owner password> -s "Type a subject line"
-r <your email address> -f <full path to your temporary message text file>

Question:
How can I quickly disable email messages going to a specific user?

Answer: You can the set the user’s email address to an empty string. This has
to be done via DQL or API commands because Documentum Administrator requires you to enter a non-zero-length email address.

UPDATE dm_user OBJECTS SET user_address='' WHERE user_name='James Brown'

Question:
Does Documentum provide any additional documentation related to
troubleshooting email notifications?

Answer: Yes, check out the document “Email Notification Troubleshooting Guide.pdf”
available from the Documentum/EMC support site.