Learn to configure and customize Documentum’s email facilities to meet the needs of your organization.
Blue Fish Development Group
701 Brazos St. #700
Austin, TX 78701
(512) 469-9300
Learn to configure and customize Documentum’s email facilities to meet the needs of your organization.
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.
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.
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:
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.
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 Documentum\product\<server_version>\bin, This executable can be used with MAPI-supporting email servers like Lotus Notes.
Figure 1: Email Control Flow
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.
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.
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.
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>'
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>'
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.
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.
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.
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 Content Server ships with several Docbasic methods that generate email messages. These methods are located in Documentum’s installation home directory under Documentum\product\<server_version>\bin. For Content Server 5.3 these are the methods provided:
For Web Publisher workflow task notifications the methods is the following:
Available from Documentum Support for DCM-enabled systems:
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.
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'
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.
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 & """."
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 (_
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.”
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. 
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 \Documentum\product\<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.
(0 votes, average: 0 out of 5)
Loading ...Subscribe to our newsletter to be notified when new articles are posted. You can unsubscribe at any time.
You must be logged in to post a comment.