Implementing Policy › Policy Implementation › Notifications › How to Configure the Mailbox to Handle Inbound Emails

How to Configure the Mailbox to Handle Inbound Emails

Email lets you communicate with end users, such as employees or customers. The mailbox in CA SDM handles inbound emails from users and provides action according to the email. For example, the user sends an email to CA SDM to create an incident. Mailbox checks the email, creates an incident, and sends a notification back to the user stating that the incident has been created successfully.

CA SDM provides a default mailbox (named Default) that is active and that you can use in your organization. You can modify the default mailbox, create additional mailboxes, or both. After you have created a mailbox or modified the Default mailbox, you define the mailbox rules. Mailbox rules let you configure any actions, replies, or both, that must occur for messages retrieved from a mailbox.

The following diagram shows how to configure the mailbox to handle inbound emails:

Follow these steps:

1. Open the CA SDM Web UI.
2. Choose a Notification Phrase.
   • Activate a Predefined Notification Phrase.
   • Create a Notification Phrase.
3. Configure the Mailbox.
   • Edit the Default Mailbox.
   • Create a Mailbox.

Open CA SDM Web UI

Log in to the web UI from the following servers, depending on your CA SDM configuration:

• Conventional: Primary or secondary servers
• Advanced availability: Application or background servers

Choose a Notification Phrase

The notification phrase is sent to the sender of the email. For example, to confirm that an incident has been created successfully. CA SDM provides predefined notification phrases which are set to inactive by default. You can activate and modify the phrases. You can also create notification phrases to best suit your organization needs.

Choose from the following options:

• Activate a predefined notification phrase.
• Create a notification phrase

Activate a Predefined Notification Phrase

By default, predefined notification phrases are set to inactive. You activate a notification phrase so that the notifications can use the phrase.

Note: If multi-tenancy is installed, select the appropriate tenant from the drop-down list. The public (shared) option creates the object for all tenants.

Follow these steps:

1. Select Notifications, Notification Phrases on the Administration tab.

   The Notification Phrase List page opens.

2. Search for the notification phrase.
3. Click the phrase that you want to activate. For example, select Notify History - Change.

   The Notification Phrase Detail page opens.

4. Click Edit.

   The Update Notification Phrase page opens.

5. Select Active from the Active drop-down list.
6. (Optional) Modify the other fields, if necessary. For example, change the phrase.
7. Click Save.

   The Notification Phrase Detail page opens.

8. Click Close Window.

   The notification phrase is active.

Create a Notification Phrase

You can create notification phrase that contain standardized text and macros. This notification phrase is sent as a response to emails from users.

Note: If multi-tenancy is installed, select the appropriate tenant from the drop-down list. The public (shared) option creates the object for all tenants.

Follow these steps:

1. Select Notifications, Notification Phrases on the Administration tab.

   The Notification Phrase List page opens.

2. Click Create New.

   The Create New Notification Phrase page opens.

3. Complete the Notification Phrase Fields, as appropriate.
4. Click Save.

   The notification phrase is created.

Notification Phrase Fields

Complete the following fields to edit or create a notification phrase:

Symbol

Defines a unique identifier for this record.

Code

Specifies a unique value to use for the notification phrase, in the usp_notification_phrase table. The usp_notification_phrase table lists common phrases that notification message templates can use. For information about the usp_notification_phrase table, see the Technical Reference Guide.

Phrase

Specifies the phrase for the notification. You can specify both plain-text and HTML versions. HTML consolidates most whitespace into single spaces, so you must specify line breaks or paragraph breaks with tags.

For example, the following plain-text phrase is used in the Confidential Notice notification phrase:

This e-mail and any files transmitted with it are for the sole use of the intended recipient(s) and contain information that may be privileged and confidential. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient of this e-mail, please delete this e-mail and any files transmitted with it and notify the sender immediately.

The following HTML phrase can be used to ask the user to view the notification list:

Click on the following URL to view Notification List:
@{call_req_id.web_url}+HTMPL=cr_lr.htmpl+INSTANCE=@{id}

For more information about phrases, see the Notification Codes and Phrases topic.

Notification Codes and Phrases

Notification phrases let you add a standardized piece of information or text to a number of different notification messages, without having to enter and maintain the text or formulae separately in each notification template. For example:

Reply to this notification to add additional information to the ticket

Phrases standardize text for use in multiple message templates. For example, you can maintain a common phrase such as a confidential notice in a single record and use it in multiple message templates. Notification phrases are also useful for message replies, such as a Reply Notice, or a web URL link. CA SDM provides phrases and you can create your own phrases. You can set a phrase as active or inactive for use in a message template globally. (Notification phrases are inactive by default.) When a phrase is inactive, the phrase is suppressed in all message templates that use the phrase.

Notification phrases can also be used in the automatic responses to incoming email messages. The processing context for this type of message is different; omit the prefix (change_id., issue_id., call_req_id.) used in certain macros such as ref_num and web_url for phrases that the message uses. As a result, you cannot share notification phrases between notification templates and email automatic responses.

For example, some of the phrases that CA SDM provides are as follows:

Example: New Phrases

The following phrases are examples of phrases that you can create:

Note: Use separate phrases for the plain-text and HTML versions of message templates or email auto-replies. HTML consolidates most whitespace into single spaces, so line- or paragraph-breaks must be specified with tags. HTML tags included in plain-text versions of messages are displayed rather than processed.

Notification Phrase Syntax

You insert notification phrases in message templates and email reply messages using the following macro syntax:

@{notification_phrase[code].phrase}

code

Specifies the unique Code value, such as ConfidentialNotice, of the Message Phrases (usp_notification_phrase) table.

Note: The usp_notification_phrase table lists common phrases that notification message templates can use. For information about the usp_notification_phrase table, see the Technical Reference Guide.

For example:

@{notification_phrase[IncidentURL1].phrase}

@{notification_phrase[RequestReply].phrase}

When CA SDM locates the macro, the phrase text from the usp_notification_phrase table replaces the syntax. If no matching code exists (or if it is inactive), an empty string replaces the macro. No errors are written to the standard log (STDLOG), instead a warning message is logged to help you resolve potential problems.

Note: Embedding phrases within other phrases is limited to a maximum depth value that you configure by setting the NX_MAX_EXPAND_DEPTH environment variable. This limitation prevents problems which can occur when processing phrases that are accidentally self-referenced (embed themselves) or circular-referenced (when a phrase embeds a phrase into which it is embedded).

Example: How Notification Phrases Appear in a Message

This example demonstrates how notification phrases appear in a notification message. The example uses the following codes and phrases:

The following message template includes the notification phrases:

@{call_req_id.type.sym} @{call_req_id.ref_num} Closed.
Assigned to: @{call_req_id.assignee.combo_name}
Customer: @{call_req_id.customer.combo_name}
Description: @{call_req_id.description}

@{notification_phrase[IncidentURL].phrase} 
@{notification_phrase[IncidentReply].phrase}

@{notification_phrase[ConfidentialNotice].phrase}

The phrases appear in a message as follows:

Incident 1234 Closed.
Assigned to: Analyst, Joe
Customer: Doe, John
Description: This is a description of my problem

Click on the following URL to view:
http://helpdesk/CAisd/pdmweb.exe?OP=SEARCH+FACTORY=chg+SKIPLIST=1+QBE.EQ.id=400723

In order to add a comment to your Incident, just reply to this email or include the line below (on a line by itself).
%incident_id=1234

This e-mail and any files transmitted with it are for the sole use of the intended recipient(s) and contain information that may be privileged and confidential. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient of this e-mail, please delete this e-mail and any files transmitted with it and notify the sender immediately.

Mailboxes

CA SDM provides a default mailbox to connect to the mail server. You can configure this default mailbox to change the password, user name, hostname, and so on. You can also create additional mailboxes to suit your organization needs. Each mailbox can have its own definition, instead of using a single global set of definitions. You can define multiple mailboxes and use different templates or default values for each mailbox. Multiple definitions let individual tenants use separate mailboxes, or let an individual tenant or organization use different mailboxes, and have different behaviors for each mailbox.

Choose one or both of the following possibilities:

Important! We recommend that you set the associated mailbox to Inactive before you configure a mailbox rule. Otherwise, any messages that the mail server retrieves between your first change and the last change are processed with whatever rules are in effect when the message is retrieved.

• Edit the default mailbox.
• Create a mailbox.

Edit the Default Mailbox

CA SDM provides an active default mailbox that you can edit to suit the incoming mail delivery needs of your organization.

Follow these steps:

1. Select Email, Mailboxes from the Administration tab.

   The Mailbox List page opens.

2. Click Default from the Name column.

   The Default Mailbox Detail page opens.

3. Click Edit.
4. Complete or update the other fields as appropriate:

   Check Interval

   Specifies the time after which the mail server is polled for new emails.

   Active

   Indicates the mailbox status.

   Email Type

   Specifies the protocol that the mail server uses. CA SDM supports both POP3 and IMAP4. If you choose IMAP4, CA SDM polls only the Inbox folder from the mailbox.

   Hostname

   Specifies the hostname of the email server.

   Port Override

   Specifies the port number when the default port number is overridden.

   User Name

   Specifies the user ID on the mail server.

   Password

   Specifies the password on the mail server.

   Security Level

   Specifies the SMTP security level.

   Attachment Repository

   Specifies the repository where the email attachments are stored.

   Attach Entire Email

   Specifies whether to allow entire email as an attachment.

   Force Attachment Splitout

   Specifies whether to split all attachments in the email when an entire email is added as an attachment. The email and its attachments are split into separate files and attached to the tickets. Only applicable when the Attach Entire Email option is selected.

   Allow Anonymous

   Specifies whether tickets can be created from anonymous mails.

   Save Unknown Emails

   Specifies whether to save the emails that the rules defined in the mailbox did not process. These emails are stored in $NX_ROOT/site/mail_unknown.

   Use Reply-To Address

   Specifies whether to use the alternate email address for replies.

   Use TLS

   Specifies whether to use Transport Layer Security support in emails.

   CA Certificate Path

   Specifies the path where the trusted certificate has been deployed.

   Note: For the advanced availability configuration, ensure that you deploy the trusted certificate on the same location for both background and standby servers. CA SDM supports only Base-64 encoded (PEM) format for CA Certificates.

5. (Optional) Create or update the mailbox rules and policies as appropriate.

   Note: The rules that are applicable for one mailbox cannot be associated with another mailbox. To reuse the same rules for a different mailbox, recreate them for the other mailbox. You can also copy the existing mailbox.

   Important! We recommend that you set the associated mailbox to inactive before you configure a mailbox rule. Otherwise, any messages that the mail server retrieves between your first change and the last change are processed with whatever rules are in effect.

6. Click Save.

   The changes to the default mailbox are saved and applied. The first poll occurs after one second.

Multiple Mailboxes

CA SDM can process and manage multiple mailboxes. Each mailbox can have its own definition, instead of using a single global set of definitions. You can define multiple mailboxes and use different templates or default values for each mailbox. Multiple definitions let individual tenants use separate mailboxes, or let an individual tenant or organization use different mailboxes, and have different behaviors for each mailbox. You can set up multiple mailboxes by using the Administration interface. Each mailbox uses the following tables:

• usp_mailbox—Defines the mailbox.
• usp_mailbox_rule—Specifies a set of rules for each mailbox.

  Because mailbox rules supply Text API defaults, you can establish email interfaces with other software and parameters (such as category, assignee, and so on) that are configured specifically for the interface.

Note: IMAP servers support multiple mailboxes for a single account, but alternate mailboxes are not supported; only the default inbox is supported.

How Multiple Mailboxes Use Rules

The Mail Eater (pdm_maileater_nxd) component on the primary server uses mailbox connections and rules to read and process messages from one or more accounts on one or more mail servers. The Mail Eater processes mailboxes serially (only one mailbox is processed at a time), and processes rules in sequence number order.

Multiple mailboxes use rules as follows:

1. Upon primary server startup, the Mail Eater reads the following tables:

   usp_mailbox

   Represents a connection to a mail server.

   usp_mailbox_rules

   Represents the rules that apply to the connection (usp_mailbox).

   Contact_Method

   Represents the Contact Methods used for automatic replies.

   Document_Repository

   Represents the Document Repositories for storing attachments.

   The Mail Eater automatically detects changes to the objects in any of these tables, including the addition of additional objects. If a change is made to usp_mailbox or usp_mailbox_rule, the polling interval for the affected mailbox is rescheduled to one second after the change is applied.

2. At the interval defined by each mailbox, the Mail Eater retrieves each email in the inbox for the associated account, and processes the email as follows:
   1. Checks the email address for policy violations. When the Mail Eater finds a violation, processing stops, and the standard log is affected according to the mailbox definition.
   2. Compares the email to each rule (mailbox_rule) that belongs to that mailbox.
   3. If a matching rule is found, submits the message to the Text API for posting, and replies to the user as appropriate based on the specified action for the rule.

      For reply emails, the filter string identifies the object and uses the Text API for processing. After processing is complete, the response goes either to the Reply to or the From address.

   4. After the Mail Eater finds a matching rule, no other rules are checked, and the Mail Eater processes the next email in the inbox.
   5. If no matching rule is found, the message is discarded.
3. After the Mail Eater processes all emails for an inbox, the processed and discarded messages are purged from the mail server, and the next processing interval is scheduled.

Create a Mailbox

You can create a mailbox that connects to the mail server, and that you configure to set values for host, user, password, and so on.

Follow these steps:

1. Select Email, Mailboxes from the Administration tab.

   The Mailboxes List page opens.

2. Click Create New.

   The Mailbox Detail page opens.

3. Complete the fields as appropriate:

   Check Interval

   Specifies the time after which the mail server is polled for new emails.

   Active

   Indicates the mailbox status.

   Email Type

   Specifies the protocol that the mail server uses. CA SDM supports both POP3 and IMAP4. If you choose IMAP4, CA SDM polls only the Inbox folder from the mailbox.

   Hostname

   Specifies the hostname of the email server.

   Port Override

   Specifies the port number when the default port number is overridden.

   User Name

   Specifies the user ID on the mail server.

   Password

   Specifies the password on the mail server.

   Security Level

   Specifies the SMTP security level.

   Attachment Repository

   Specifies the repository where the email attachments are stored.

   Attach Entire Email

   Specifies whether to allow entire email as an attachment.

   Force Attachment Splitout

   Specifies whether to split all attachments in the email when an entire email is added as an attachment. The email and its attachments are split into separate files and attached to the tickets. Only applicable when the Attach Entire Email option is selected.

   Allow Anonymous

   Specifies whether tickets can be created from anonymous mails.

   Save Unknown Emails

   Specifies whether to save the emails that the rules defined in the mailbox did not process. These emails are stored in $NX_ROOT/site/mail_unknown.

   Use Reply-To Address

   Specifies whether to use the alternate email address for replies.

   Use TLS

   Specifies whether to use Transport Layer Security support in emails.

   CA Certificate Path

   Specifies the path where the trusted certificate has been deployed.

   Note: For the advanced availability configuration, ensure that you deploy the trusted certificate on the same location for both background and standby servers. CA SDM supports only Base-64 encoded (PEM) format for CA Certificates.

4. Click Create New from the Rules tab to create a mailbox rule.

   The Create New Mailbox Rule page opens.

   Note: The rules that are applicable for one mailbox cannot be associated with another mailbox. To reuse the same rules for a different mailbox, recreate them for the other mailbox. You can also copy the existing mailbox.

   Important! We recommend that you set the associated mailbox to inactive before you configure a mailbox rule. Otherwise, any messages that the mail server retrieves between your first change and the last change are processed with whatever rules are in effect.

5. Complete the Mailbox Rule Fields as appropriate and click Save.
6. Select the Policy tab to define the mailbox policies to protect your organization against certain types of email abuse. Complete the Mailbox Policy Fields as appropriate and click Save.

   The mailbox is created.

   If you are using multiple mailboxes, the Mail Eater (pdm_maileater_nxd) component uses mailbox connections and rules to read and process messages from one or more accounts on one or more mail servers. The Mail Eater runs on the following servers, depending on your CA SDM configuration:

   • Conventional: Primary server
   • Advanced availability: Background server

   The Mail Eater polls the mailboxes serially (only one mailbox is processed at a time), and processes rules in sequence number order, as follows:

   1. Upon the startup of the primary or background server, the Mail Eater reads the following tables in the database:

      usp_mailbox

      Represents a connection to a mail server.

      usp_mailbox_rules

      Represents the rules that apply to the connection (usp_mailbox).

      Contact_Method

      Represents the Contact Methods that are used for automatic replies.

      Document_Repository

      Represents the Document Repositories for storing attachments.

      The Mail Eater automatically detects changes to the objects in any of these tables, including the addition of extra objects. If a change is made to usp_mailbox or usp_mailbox_rule, the polling interval for the affected mailbox is rescheduled to one second after the change is applied.

   2. At the interval that is defined by each mailbox, the Mail Eater retrieves each email in the inbox for the associated account, and processes the email as follows:
   3. Checks the email address for policy violations. When the Mail Eater finds a violation, processing stops, and the standard log is affected according to the mailbox definition.
   4. Compares the email to each rule (mailbox_rule) that belongs to that mailbox.
   5. If a matching rule is found, submit the message to the Text API for posting, and replies to the user as appropriate based on the specified action for the rule.

      For reply emails, the filter string identifies the object and uses the Text API for processing. After the processing is complete, the response goes either to the Reply to or the From address.

   6. After the Mail Eater finds a matching rule, no other rules are checked, and the Mail Eater processes the next email in the inbox.
   7. If no matching rule is found, the message is discarded.

      After the Mail Eater processes all emails for an inbox, the processed and discarded messages are purged from the mail server, and the next processing interval is scheduled.

Create a Mailbox Policy

You can create policies that apply to any actions, replies, or both, that must occur for mail delivery to an inbox.

To create a mailbox policy

1. On the Administration tab, select Email, Mailboxes.

   The Mailboxes List page appears and lists attributes.

2. Click the name of the mailbox for which you want to configure policies.

   The Mailbox Detail page appears.

3. Click the Policy tab.

   Policy details associated with the mailbox appear.

4. Click Edit.

   You can edit the fields.

5. Complete the fields as appropriate.
6. Click Save.

   The mailbox policy is set, and takes effect immediately.

Email Address/Hour

Specifies the maximum number of emails per email address per hour. You can specify the following values:

• -1—No limit (default)
• 0—No emails allowed.
• 1—Maximum number of emails allowed.

Log Violation

Logs the violation to the standard log. You can specify the following values:

• Do not log
• First violation only (default)
• All violations

Note: The First violation only option keeps a list of email addresses associated with messages that violate mailbox policies and uses the list for the log to avoid duplicate log entries. The list is cleared when the Mail Eater daemon is restarted. However, if you change the setting from First violation only to one of the other options and back, the list of email addresses which were logged under this setting is not cleared. If a mailbox logs numerous violations while using this setting, we recommend that you restart the Mail Eater daemon periodically to clear the list, or use the Do not log option.

Inclusion List

Specifies email addresses or domains that are allowed to process emails—only emails matching the list are allowed. You can specify multiple addresses or domains by delimiting them with a comma, semicolon, space character, or line break. An entry of an asterisk (‘*’) by itself is the “World Domain,” and matches all domains that are not in the Exclusion List.

Exclusion List

Specifies email addresses or domains that are not allowed to process emails. You can specify multiple addresses or domains by delimiting them with a comma, semicolon, space, or line break.

Note: Addresses in the Exclusion List override any values in the Inclusion List. Addresses in the Inclusion List override domains in the Exclusion List, and can provide specific exemptions for specific senders in an otherwise-banned domain. Domains in the Exclusion List override the World Domain in the Inclusion List. The World Domain is not valid in the Exclusion List.

Mailbox Policy Fields

You can use the following fields to implement the policy:

Email Address/ Hour

Specifies the number of emails per hour that any one email address is permitted to send to that mailbox. If an email address exceeds the limit, the email address is added to the exclusion list. No more messages from that sender email address are processed for that mailbox until you remove the email address from the exclusion list.

Log Violation

Specifies whether to log the email addresses that violate the policy, in the stdlog file.

Inclusion List

Specifies the email addresses (for example, user@company.com) or email domains (for example, company.com) that are allowed to send emails.

The default inclusion list for each mailbox is an asterisk (*). An asterisk by itself as a whole name in this list specifies the World Domain, and represents all email domains not included in the exclusion list. This representation prevents ambiguity of whether the inclusion list is the complete list of permitted domains or the exceptions to domains in the exclusion list as follows:

• An inclusion list that includes World Domain specifies that all other entries in the inclusion list are exceptions to the exclusion list, and only domains or addresses in the exclusion list are blocked (with the exception of specific addresses in the inclusion list).
• An inclusion list that does not contain World Domain specifies that only addresses and domains listed in the inclusion list are permitted to post, and only if the sender domain (if the specific address is not in the inclusion list) or address are not in the exclusion list.

Exclusion List

Specifies the email addresses (for example, user@company.com) or email domains (for example, company.com) that are not allowed to send emails.

Note: Mailbox policies pertain to the single associated mailbox only. An address which is added automatically to one mailbox exclusion list for violating the maximum number of emails restrictions is not added automatically to the exclusion list for any other mailboxes, nor is the email count used for other mailboxes.

Mailbox Rule Fields

Complete the following mailbox rule fields, as appropriate:

Sequence

Specifies the sequence number of the rule. Messages are checked against rules in sequence number order from lowest to highest.

Mailbox

Specifies the mailbox to which this rule belongs.

Active

Sets the rule to active or inactive.

Filter

Specifies what part of the email to search for the filter pattern, for example, Subject contains. For more information, see the Pattern Matching in Mailbox Rules topic.

Filter String

Specifies a regular expression string to match with the email content. For example, [ \t\r\n]request[ \t\r\n]. The placeholder {{object_id}} lets you specify the artifact value for the Text API to use for associating the message with a specific ticket. For more information, see the Filter String Object Identifier Restrictions and Special Characters in Regular Expressions topics.

Ignore Case

Specifies whether to consider letter case when matching patterns.

Action

Specifies the action to take when the filter criteria matches, for example, Create/Update Object.

Note: For information about rule actions, see the Administration Guide.

Action Object

Displays the type of ticket object to which message actions apply, for example, Request.

Minimum Artifact Type

Sets the minimum type of artifact checking that you want to allow:

NONE

Specifies no validation of artifacts. This value is the same as not adding the keyword to the input file. Also accepts Text API ticket ID commands.

PROTECTED

Validates a ticket against the hash for confirmation. If confirmation fails, the artifact is considered invalid and the email fails filtering where filtering is looking for an artifact ({{object_id}}).

SECURE

Validates the ticket number from an encrypted data block. If the value is not a valid encrypted ticket number, the artifact is considered invalid and the email fails filtering where filtering is looking for an artifact ({{object_id}}).

Note: Types that are more secure than what is set are allowed. In other words, if you set the minimum type to PROTECTED, then both PROTECTED and SECURE are allowed, but NONE is not. Also, if PROTECTED or SECURE are selected, Text API ticket ID commands are not accepted. For more information about the artifiacts, see the Artifacts Use Considerations topic.

Reply

Specifies a notification method to send an automatic response. For example, Email. If you do not set this option, no response is returned. The response indicates success or failure of the actions performed for the message, and is separate from any notifications. If you are using multiple mailboxes, we recommend you to use the notification method to configure email replies.

Reply Subject

Specifies a subject line for the reply, for example, Service Desk Response.

Write to stdlog

Write email text to the standard log (stdlog) if the filter matches.

Log Entry Prefix

Specifies a prefix to add when writing email text to the standard log entries. Use this option to enable matching log entries to rules.

Add Subject Line

Adds the subject line from the original message to the message body before processing. You can append, prepend, or not add a subject line. The subject line is attached to either the ticket Description or a Log Comment, depending on the actions for the message.

Text API Defaults

Specifies additional default commands for the Text API when the filter matches. Combines with the contents of the [EMAIL_DEFAULTS] section of the text_api.cfg file. The TextAPI Defaults field includes TextAPI keyword commands that are applied to a ticket when it is created from an email that matches a mailbox rule. The commands are not applied when the message affects an existing ticket.

To specify TextAPI Defaults commands, place each command on a separate line in the TextAPI Defaults field. Format the commands as follows:

OBJECT.FIELD=value

Note: Do not include a leading percentage symbol (%), which is required only for corresponding commands that are embedded in the body of the email.

For example, format the commands as follows:

REQUEST.PRIORITY=3

PROBLEM.CATEGORY=Facilities

INCIDENT.GROUP=Plumbing

Text API Ignore Incoming

Specifies additional Ignore Details for the Text API when the filter matches. Combines with the contents of the [EMAIL_IGNORE_INCOMING] section of the text_api.cfg file.

The TextAPI Ignore Incoming field lists TextAPI keyword commands that are not permitted to be used in the text of the incoming email message. Any commands that are listed in this field are ignored when they are found in an incoming email message.

To specify TextAPI Ignore Incoming commands, do the following steps:

1. Place each command on a separate line in the TextAPI Ignore Incoming field.
2. Format the commands as follows:

   OBJECT.FIELD
   

   Note: Do not include a leading percentage symbol (%), which is required only for the corresponding commands that are embedded in the body of the email.

   For example, format the commands as follows:

   CHANGE.ASSIGNEE
   

   PROBLEM.GROUP
   

   REQUEST.EFFORT
   

3. Define all commands used in either field in the [KEYWORDS] section of the text_api.cfg file. This file is located in the “site” subdirectory of the CA SDM installation directory.

Details

Specifies information about the rule.

Success Text

Specifies the plain-text contents of a reply message when the message is processed successfully. For example:

Thank you for submitting an update to your request. A support technician will contact you within the next 24 hours.

You can also enter a notification phrase, if already created. For example, you can use a notification phrase for email auto-replies.

Thank you for submitting your request.

@{notification_phrase[notification phrase code].phrase}

Success HTML

Specifies HTML contents of a reply message when the message processes successfully. The following options let you edit and preview HTML text:

Edit Success HTML

Opens the HTML Editor which you can use to format the HTML.

Quick View

Previews the HTML.

HTML Source

Shows the HTML source.

You can also use a notification phrase, for example,

Thank you for submitting your request.</p>

@{notification_phrase[notification phrase code].phrase}</p>

Failure Text

Specifies the plain-text contents of a reply message when the message does not process successfully. You can also enter a notification phrase, if already created. For example, you can use the following text:

Thank you for submitting your request.

@{notification_phrase[notification phrase code].phrase}

Failure HTML

Specifies HTML contents of a reply message when the message does not process successfully.

Create a Mailbox Rule

You can create rules that recognize specific keywords or elements of the incoming messages, and perform any actions, replies, or both, that must occur for incoming messages which contain those keywords or elements.

Note: The rules that are applicable for one mailbox cannot be associated with another mailbox. To reuse the same rules for a different mailbox, recreate them for the other mailbox. You can also copy the existing mailbox.

Important! We recommend that you set the associated mailbox to inactive before you configure a mailbox rule. Otherwise, any messages that the mail server retrieves between your first change and the last change are processed with whatever rules are in effect.

To create a mailbox rule

1. On the Administration tab, select Email, Mailbox Rules.

   The Mailbox Rules List page appears and lists rules.

2. Click Create New.

   The Mailbox Rule Detail page appears.

3. Complete the fields as appropriate.
4. Click Save.

   The mailbox rule is created and in effect.

Mailbox Rule Actions

Mailbox rules let you perform any of the following email actions:

• Ignore Email—Does not process the email and does not reply.

  This action is useful for system-level messages such as Out of Office or Mail Delivery errors.

• Ignore Email and Reply—Does not process the email, and replies to the sender. Response emails use the reply success messages and the reply failure messages are ignored.
• Update Object—Uses the filter string to determine the object identifier (for example, %Incident:{{object_id}}% in the email), and sends an update request to the Text API. If the object identifier is not found, the Text API does nothing.

  This action typically handles email replies where the object identifier is embedded in the email. If no object identifier is present, the failure response message is typically sent.

• Create/Update Object—Uses the filter string to determine the object identifier (for example, %Incident:{{object_id}}% in the email), and sends an update request to the Text API. If the object identifier is found, the Text API updates a ticket. If the object identifier is not found, the Text API creates a ticket.

  This action is the standard behavior of the mail daemon (Mail Eater) in which the email does or does not contain Text API keywords.

Note: For information about configuring mailbox rules, see the Online Help.

Pattern Matching in Mailbox Rules

Mailbox rules use regular expressions for pattern matching. Consider the following whitespace characters that apply to regular expressions in mailbox rules:

\t

Specifies a horizontal tab.

\r

Specifies a carriage return character.

\n

Specifies a line feed or new line character.

The characters that represent line breaks in text can vary with the operating system, mail server, and mail client, for example:

• UNIX uses a \n.
• Microsoft uses \r\n
• Macintosh uses \r
• MacOS X uses \n

In certain circumstances, the mail processing elements of CA SDM exchange substitute one of these line break characters for another to establish or maintain a distinction between different text elements, such as message text and attached parameters. As a result, when you want to use a line or paragraph break, build your filters so that either \r or \n can be matched, whichever is found. If you want to indicate a line break between two keywords, build your filters so that a sequence of one or more \r and \n characters can be matched.

Line wrapping by the mail client that sends a message can cause unexpected line breaks to appear in the middle of the text which is expected to match your filter string, when the filter string searches the body of the message. A space can change to a carriage return, line feed, or both, or the carriage return, line feed, or both can be inserted after a space. If a message is composed in HTML, and contains bulleted or numbered lists or indented paragraphs, tabs can also be present after the mail client converts and sends the message. When you include spaces in the middle of a filter string, use a Regular Expression block which represents any whitespace of variable size. This block is [ \t\r\n]+ (open-bracket, space, backslash, t, backslash, r, backslash, n, close-bracket, plus sign), and represents any sequence of one or more spaces, tabs, carriage returns, and line feeds.

Example: Use [ \t\r\n] to Match a Keyword Exactly

This example demonstrates how you can use whitespace characters to match the keyword "request" and not match other possible keywords such as the following words:

requester
requesting
requested
orequestra

To match only the keyword request, precede and follow the keyword request by one or more whitespace characters as follows:

[ \t\r\n]request[ \t\r\n]

The Mail Eater matches only the word request or the word as part of a sentence, and not as part of another word such as requester.

Filter String Object Identifier Restrictions

Restrictions apply to the mailbox rule filter strings which determine the object identifier (for example, %Incident:{{object_id}}%) in an email. Text that surrounds an object identifier ({{object_id}}) must be unambiguous in both content and length; the text must clearly define the beginning and end of the ticket ID artifact value that is between the text.

The following restrictions apply to how the Mail Eater interprets the start of the ticket ID artifact value:

• The {{object_id}} placeholder must not be the first element in the filter string. At least one character is required, and generally a distinctive keyword, or a sequence of letters, numbers, and symbols must precede the object ID keyword.
• The character that immediately precedes the {{object_id}} placeholder must not be a repeatable or optional character (meaning, a character that a plus sign (+), an asterisk (*), or a question mark (?) follows) that can be part of a ticket ID artifact value. Repeatable or optional characters risk being ambiguous with the start of the ticket ID artifact value, unless they are whitespace characters. Whitespace characters (space, tab, carriage return, line feed) must not be part of a ticket ID artifact value.
• The character that immediately precedes the {{object_id}} placeholder must not be a repeatable or optional bracketed-set of characters which includes characters that can be part of a Ticket ID Artifact value.

The following restrictions apply to how the Mail Eater interprets the length of the ticket ID artifact value:

• The {{object_id}} placeholder must not be the last element in the Filter String. One or more characters must follow the {{object_id}} placeholder.
• The character that immediately follows the {{object_id}} placeholder must not be a repeatable or optional character (meaning, a character that a plus sign (+), an asterisk (*), or a question mark (?) follows) that can be part of a ticket ID artifact value. Repeatable or optional characters risk being ambiguous with the end of the ticket ID artifact value, unless they are whitespace characters. Whitespace characters (space, tab, carriage return, line feed) must not be part of a ticket ID artifact value.
• The first character after the {{object_id}} placeholder must not be a character that can be part of a ticket ID artifact value.
• Avoid the following characters immediately before and after the {{object_id}} placeholder:
  • All upper or lower-case letters
  • Numerals
  • The plus sign (+)
  • The slash (/)
  • The comma (,)
  • The period (.), because it can represent any character except for a line break, and thus can be any of the characters in this list.

  Any of these characters can exist within the ticket ID artifact value. When a bracketed set (several characters between brackets, of which the filter check can match any one), precedes or follows the {{object_id}} placeholder, the bracketed set must not contain any of these characters.

Special Characters in Regular Expressions

Pattern matching for the filters in mailbox rules follows the rules for ASCII Regular Expressions with C-style special characters.

Important! We recommend that you are familiar with Regex syntax to use special characters in regular expressions.

For example, consider the following special characters for Regex patterns that apply to regular expressions in mailbox rules:

\t

Specifies a horizontal tab. In filter strings for mailbox rules, \t matches the beginning and end of text (and tabs), and is specific to the Mail Eater.

\r

Specifies a carriage return (return to the beginning of the current line).

Note: Do not use \r for searching message subjects or sender addresses.

\n

Specifies a newline (combination of line feed and carriage return).

Note: Do not use \n for searching message subjects or sender addresses.

\t, \r, and \n are the special characters that occur most often in regular expressions for mailbox rules.

Example: \t, \r, and \n Use

[ \t]request[ \t]

Searches text for the word request. The brackets match any one character from the set, including the space, so [ \t] matches a space or a tab.

[\r\n]+critical[ \t\r\n]

Searches text for the word critical at the start of a line, the start of the message, or as the entire contents of a line. The brackets match any one character from the set, and the + (plus sign) matches one or more of the previous, so [\r\n]+ matches one or more carriage returns and newlines.

Sample Text for Notification Phrases in a Mailbox Rule

This example shows sample text that you can use to include notification phrases in a mailbox rule. You define separate versions of a notification phrase for plain text and for HTML when the phrase contains any line breaks or other formatting.

Use the following text in Success Text, Success HTML, or both fields on the Update Mailbox Rule page, Reply Success tab:

• Success Text

  Thank you for submitting your request.
  @{notification_phrase[IncidentURL1].phrase}
  

• Success HTML

  Thank you for submitting your request.</p>
  @{notification_phrase[IncidentURL1H].phrase}</p>
  

Note: For more information about Notification Phrases that is defined under Administration Tab, Notifications, Notification Phrases, see the Online Help.

More information:

Notification Codes and Phrases

Notification Phrase Syntax

Artifacts Use Considerations

An email artifact refers to something that arises from the mail process, for example, an email address that is included in a forwarded email. The Text API uses artifacts that contain a ticket ID (such as a reference number) for reply support. When the ticket ID is found, an existing Text API keyword (such as %INCIDENT_ID) is set and added to the input for the Text API. The Mail Eater identifies that a reply is associated with a particular ticket by finding the artifact in the message.

The Mailbox rules let you specify the artifact and the value that the Text API uses. For example, you can define a rule for incidents as Incident:{{object_id}}%. When a rule finds Incident:1234, the Text API uses %INCIDENT_ID=1234 (1234 is the ref_num for the Incident). Because the artifact must be unique in an email and easy to find, you can make the artifact more distinctive such as %Incident:{{object_id}}%. A percentage sign (%), whitespace, or some other character that cannot appear in an artifact value must follow {{object_id}}. Uppercase and lowercase letters, numbers, forward slashes, commas, and plus symbols are potentially part of a value. The secure artifacts are Base64-encoded after encryption. If you do not use the Secure artifacts, the characters that follow the artifact must not be contained in the ticket ID suffix, if any, which has been configured for that type of ticket.

When using the filter string of the mailbox rules to identify the ticket ID Artifact, the keyword {{object_id}} represents the position in the filter string where the ticket ID artifact is expected. This keyword is case-sensitive, even if the mailbox rule is not.

Example: Email Artifact Use

The following example shows an ARTIFACT format for use in a mailbox rule for a change request ticket.

Usage: %REQUEST=@{call_req_id.ref_num}%

Example: %REQUEST=1234%

When you construct the filter string of the mailbox rule, consider the following conditions:

• A clear boundary must exist between the ticket ID artifact and the keywords which precede and follow it. We strongly recommended that you include whitespace text in this boundary text.
• Do not end the portion of the filter string that precedes the {{object_id}} keyword in a repeatable or optional pattern that can match the beginning of the ticket ID Artifact, and do not end a pattern whose length is ambiguous. For example, the filter string must not contain the request(er|ed|ing)?{{object_id}}, because this construction causes an ambiguity whether a trailing er, ed, or ing is the end of the leading text or part of the prefix of an unprotected ticket ID.
• The portion of the filter string that follows the {{object_id}} keyword must not begin in a repeatable or optional pattern that may match the end of the ticket ID artifact, must not begin with a pattern whose length is ambiguous, and must contain at least one element of whitespace. For example:
  • The filter string must not contain {{object_id}}[A-Z]?, because the [A-Z]? may match the last character of the ticket ID artifact.
  • The filter string must not end with {{object_id}}Item, because it is possible for Item to appear in the ticket ID artifact, either as the suffix of a ticket ID in a plain-text or protected artifact, or as characters within a secure artifact.
  • {{object_id}} Item is acceptable, because the space cannot be part of a ticket ID artifact, and is not part of a protected or plain ticket ID artifact. However, {{object_id}}[ \t\r\n]+Item (open-bracket, space, backslash, t, backslash, r, backslash, n, close-bracket, plus sign, +Item) is better, because the [ \t\r\n]+ compensates for the mail program inserting a line break after the {{object_id}}.
• When you construct the filter strings for different mailbox rules, avoid using a filter string that completely includes another mailbox rule filter string, or in which the portion before or after a {{object_id}} keyword completely includes that portion of another mailbox rule filter string. Depending on the order in which these filters are checked, a message match intended for one filter can match with another, with a portion of the ticket ID artifact matching the additional text that distinguishes between the two filter strings.

Administration Guide - How to Create a Mailbox Rule That Matches Every Inbound Message

This new topic is for the Administration Guide in the chapter "Implementing Policy," in the section Email Administration, Mailbox Rules.

You can create a mailbox rule that matches every inbound message that another mailbox rule does not filter.

To create this type of rule, set the filter as Subject Contains and the filter string as a period and an asterisk (".*").

• A period matches any character except the line break.
• An asterisk matches zero or more occurrences of the symbol immediately before it.

As a result, this combination matches zero or more characters that are not line breaks.

Example: A "Catch-All" Mailbox Rule

This example demonstrates how you can use a ".*" combination to match every inbound message:

Filter = "Subject contains"
Filter String = ".*"

How to Use the Mailbox Rules TextAPI Defaults and TextAPI Ignore Incoming Settings

The TextAPI Defaults and TextAPI Ignore Incoming fields let you specify default values for incoming mailbox rules, and specify TextAPI commands that should not be accepted in incoming emails. These fields work with the default values that are set in the [EMAIL_DEFAULTS] section and with the forbidden-commands list in the [EMAIL_IGNORE_INCOMING] section of the text_api.cfg file. When a conflict occurs between the definition in a mailbox rule and the definition in the text_api.cfg file, the value set in the mailbox rule applies.

The TextAPI Defaults field includes TextAPI keyword commands that are applied to a ticket when it is created from an email that matches a mailbox rule. The commands are not applied when the message affects an existing ticket.

To specify TextAPI Defaults commands, do the following:

1. Place each command on a separate line in the TextAPI Defaults field.
2. Format the commands as follows:

   OBJECT.FIELD=value
   

   Note: Do not include a leading percentage symbol (%), which is required only for corresponding commands that are embedded in the body of the email.

   For example, format the commands as follows:

   REQUEST.PRIORITY=3
   PROBLEM.CATEGORY=Facilities
   INCIDENT.GROUP=Plumbing
   

The TextAPI Ignore Incoming field lists TextAPI keyword commands that are not permitted to be used in the text of the incoming email message. Any commands that are listed in this field are ignored when they are found in an incoming email message.

To specify TextAPI Ignore Incoming commands, do the following:

1. Place each command on a separate line in the TextAPI Ignore Incoming field.
2. Format the commands as follows:

   OBJECT.FIELD
   

   Note: Do not include a leading percentage symbol (%), which is required only for the corresponding commands that are embedded in the body of the email.

   For example, format the commands as follows:

   CHANGE.ASSIGNEE
   PROBLEM.GROUP
   REQUEST.EFFORT
   

3. Define all commands used in either field in the [KEYWORDS] section of the text_api.cfg file. This file is located in the “site” subdirectory of the CA SDM installation directory.