Dmemail configuration parameters

This topic describes the configuration parameters for the dmemail utility.

Configuration parameters syntax

You can specify the configuration parameters in the email_config.dat file or the command line.

Guidelines:

  • To enter a parameter, use the following syntax: keyword=value

  • The parameters are not case-sensitive.

  • A number sign (#) indicates a comment in the email_config.dat file.

  • Empty lines are allowed.

Back to top

Database processing

The following table lists the database processing parameters:

Symbol Description
DATABASE

Multiple databases can be processed in sequence, by specifying a keyword DATABASE_i, where i is an integer, such as 1 or 2, for each subsequent database to be processed.

In each case, the DATABASE key specifies the usual Dimensions CM "connection string" for a database, similarly to DMDB.

If the database requires a password to allow the user ID to connect, you can set it using the dmpasswd utility documented in the Command-Line Reference.

Example:

DATABASE_1=intermediate@dim10
DATABASE_2=intermediate@dim10-test

HOST
DMUSER

HOST and DMUSER

These are specs for a Dimensions CM server and user ID. This is required only for Dimensions RM functionality. In general operation, dmemail does not require a Dimensions server to be running, only the database to be available.

HOST_<i>

DMUSER_<i>

These operate similarly to DATABASE_<i> in the case where multiple databases are to be processed.

For details about integrating with Dimensions RM, see Dimensions RM integration.

Back to top

Processing options

The following table lists the processing parameters:

Symbol Description
PROCESS_FILES

Value: Y or N

Indicates if dmemail processes the stored "email files" and physically "posts" them to the email system. Setting this to N is useful in testing to avoid a flood of unwanted emails.

Temporary files are created, used, and then deleted for each email. During a long run of dmemail, only a handful of temporary files should exist.

Back to top

Debugging options

Change the following debugging parameters only if requested by Support.

It may be best to specify these symbols in the command line. If you set debug=y, the options in effect are printed in the log.

Symbol Description
PROCESS_ROWS

Value: Y or N

Indicates if dmemail should generate new "email files" on disk from the event record rows in the database. Setting this to N means that new events are not processed, which is helpful if you are working on fixing a problem with existing emails.

DELETE_ROWS

Value: Y or N

Indicates if dmemail should delete rows from the database once they have been dealt with. This is essential in a live operation, or the same email is regenerated repeatedly. But in testing it may be useful to keep the data for a second test.

DELETE_FILES

Value: Y or N

Indicates if dmemail should delete the physical "email files" after posting them. This is essential in a live operation, or the same email is generated repeatedly. But in testing it may be useful to avoid deleting the body files, so you can inspect them for testing purposes.

LOGGING Value: Y or N
LOG_FILE <filename>
DEBUG

Value: Y or N

Add detailed information to output, including the "symbol table" contents. The symbol table dump contains details of all symbols available for expansion in the template.

Back to top

Locating email templates

The following table lists the parameters for locating email templates:

Symbol Description
TPL_SEARCH_<i>

Here, <i> is a small number starting at 0, and is used to specify a list of locations where email templates can be found.

The reason for allowing a list of locations is so that custom versions of supplied templates can be stored in a local directory that is searched ahead of the system directory.

LOCALE_MAP_<i>

LOCALE_DIR_<i>

Here, <i> is a small number, starting at zero. For each value of i, these symbols specify a mapping from a "locale name" to a directory name.

The locale name is a string defining the preferred "language" for a particular email recipient. The resulting directory name is then added to the front of the search list defined above. This allows certain email templates to be redesigned in a language-sensitive way, while at the same time allowing the default templates to be used if no such customizing has been provided.

Example:

Copy code
TPL_SEARCH_0=c:\custom\email_templates
TPL_SEARCH_1=c:\Program Files\OpenText\Dimensions 14.7\email_templates
LOCAL_MAP_0=GERMAN
LOCAL_DIR_0=c:\custom\email_templates\german

In this example, a template is searched for in the following places:

Copy code
default:c:\custom\email_templates
c:\Program Files\OpenText\Dimensions 14.7\email_templates
German:c:\custom\email_templates\german
c:\custom\email_templates
c:\Program Files\OpenText\Dimensions 14.7\email_templates

Back to top

Miscellaneous options

The following table lists the rest of the dmemail symbols:

Symbol Description
MAX_EMAIL_LIST_SIZE

Integer.

Emails are sent using a shell command line, which may have a limited length. If this option is set to a low value (in characters), then when large distributions are generated, they are split into multiple emails, each with a smaller list of recipients.

DEFAULT_SUBJECT Specifies a default subject line to be used if the template being processed does not specify one. Most templates set the subject line, as this allows variables (such as item names) to be displayed in the subject itself.
DEFAULT_SUBJECT_MULTIPLE When multiple emails are merged together in a digest structure, this variable specifies what the default subject is.
MULTIPLE_TEMPLATE

This names a special template that is a "container" that holds the individual pieces of a merged (digest) email. It can be customized to achieve certain formatting effects.

The supplied version, multiple_notifications.tplt, uses a simple HTML splitter bar between individual email bodies. See this example for more information.

ENVELOPE

This names a special template which is used like an envelope, wrapping up the email body just prior to posting.

The supplied example, html-envelope-outer.tplt adds the necessary HTML syntax to the top and bottom of the email, to make a valid HTML message. It could be customized to add customer-specific branding to all Dimensions CM emails.

EMAIL_SLEEP

In some configurations, SMTP servers cannot respond quickly enough to a large number of emails, such as may be generated by dmemail. This could be the result of an anti-spam policy implemented by the SMTP server. This parameter specifies a value in seconds which is used as a delay between sending messages. By default, this figure is set to 30.

If you do not have any such spam policy in place, we highly recommend that you lower this to a figure of 1 or 2.

EMAIL_DIRECTORY Emails are first created as files, in this directory. If this option is not specified, the default at DM_TMP is sent.
DIGEST

This option controls the way emails are digested:

0 - No digesting for super fast processing of an email backlog. This directly sends each row.

1 - (Default) The current behavior based on digest flag against user subscription.

2 - Forced mode, which means that all messages are digested to produce only one email per user. This could be used to ease the burden on the mail server in a backlog situation.

DIGEST_THRESHOLD

This option sets the limit for the number of messages to be digested.

Numeric value. Default: 10000.

If the number of rows to be processed is larger than this, then dmemail refuses to work unless DIGEST=0 is in effect. This limit can be overridden when large runs are required.

FILTER_SQL

This option specifies a "sql where clause component" that is used to select rows from the MAILS2PROCESS table. An administrator can use this to test out situations on a live system without sending thousands of mails.

Here are some examples:

dmemail - "filter_sql=obj_uid=12345"
dmemail - "filter_sql=create_date between xxxx and yyyyy"
dmemail - "filter_sql=rel_class = 7"

The full SQL generated is shown in the log when debug=y.

Here is a typical test:

dmemail - process_files=n delete_files=n "filter_sql=obj_uid>12345"

PURGE_ROWS

Value: Y or N

If set to Y, then rows that are ignored by the filter used above, are purged from the table. If the FILTER_SQL specified a condition that requested only recent rows, then this would delete all the older rows.

This works by inverting the condition specified with FILTER_SQL.

NO_STOPFILE

Value: Y or N

Specifying this in the config file enables the command-line program to use scheduling mode, just as if it had been started from the Dimensions pool process. The syntax is:

dmemail -dmpool

For this to work, you need to set up the dm.cfg variables that control scheduling.

ALLOW_MISSING_SYMBOLS

If set to Y, the email template expands even if some variables are not defined. This is very useful for processing a batch of emails which have a known minor problem, for example, a missing description. In place of the symbol, text is generated as in the following example:

Template before expansion:

Request: %DMTEST.

Email after expansion:

Request: [symbol DMTEST is not defined]

Back to top

See also: